/ Hex Artifact Content
Login

Artifact d78bb41578104ca45d2e3e219b191f8e412bb726:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f  rve to make mino
03c0: 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a 20  r changes if.** 
03d0: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20  experience from 
03e0: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64  use "in the wild
03f0: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63  " suggest such c
0400: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65  hanges are prude
0410: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66  nt..**.** The of
0420: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67  ficial C-languag
0430: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74  e API documentat
0440: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69  ion for SQLite i
0450: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f  s derived.** fro
0460: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68  m comments in th
0470: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66  is file.  This f
0480: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f  ile is the autho
0490: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a  ritative source.
04a0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65  ** on how SQLite
04b0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
04c0: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61  suppose to opera
04d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  te..**.** The na
04e0: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  me of this file 
04f0: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74  under configurat
0500: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69  ion management i
0510: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e  s "sqlite.h.in".
0520: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65  .** The makefile
0530: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f   makes some mino
0540: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69  r changes to thi
0550: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20  s file (such as 
0560: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65  inserting.** the
0570: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29   version number)
0580: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73   and changes its
0590: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65   name to "sqlite
05a0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20  3.h" as.** part 
05b0: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f  of the build pro
05c0: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23 29  cess..**.** @(#)
05d0: 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e 69   $Id: sqlite.h.i
05e0: 6e 2c 76 20 31 2e 34 31 31 20 32 30 30 38 2f 31  n,v 1.411 2008/1
05f0: 31 2f 31 30 20 31 38 3a 30 35 3a 33 36 20 73 68  1/10 18:05:36 sh
0600: 61 6e 65 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66  ane Exp $.*/.#if
0610: 6e 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f  ndef _SQLITE3_H_
0620: 0a 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45  .#define _SQLITE
0630: 33 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73  3_H_.#include <s
0640: 74 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20  tdarg.h>     /* 
0650: 4e 65 65 64 65 64 20 66 6f 72 20 74 68 65 20 64  Needed for the d
0660: 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f  efinition of va_
0670: 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d  list */../*.** M
0680: 61 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e 20  ake sure we can 
0690: 63 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20  call this stuff 
06a0: 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66  from C++..*/.#if
06b0: 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a  def __cplusplus.
06c0: 65 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e  extern "C" {.#en
06d0: 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20  dif.../*.** Add 
06e0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06f0: 76 65 72 72 69 64 65 20 27 65 78 74 65 72 6e 27  verride 'extern'
0700: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
0710: 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69  TE_EXTERN.# defi
0720: 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  ne SQLITE_EXTERN
0730: 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a   extern.#endif..
0740: 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f  /*.** These no-o
0750: 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65  p macros are use
0760: 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e  d in front of in
0770: 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b  terfaces to mark
0780: 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66   those.** interf
0790: 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20 64  aces as either d
07a0: 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78 70  eprecated or exp
07b0: 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20  erimental.  New 
07c0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
07d0: 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64  should not use d
07e0: 65 70 72 65 63 61 74 65 64 20 69 6e 74 72 66 61  eprecated intrfa
07f0: 63 65 73 20 2d 20 74 68 65 79 20 61 72 65 20 73  ces - they are s
0800: 75 70 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77  upport for backw
0810: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
0820: 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70  ility only.  App
0830: 6c 69 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73  lication writers
0840: 20 73 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65   should be aware
0850: 20 74 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d   that.** experim
0860: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
0870: 20 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20   are subject to 
0880: 63 68 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20  change in point 
0890: 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
08a0: 54 68 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65  These macros use
08b0: 64 20 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20  d to resolve to 
08c0: 76 61 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66  various kinds of
08d0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
08e0: 74 68 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65  that.** would ge
08f0: 6e 65 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d  nerate warning m
0900: 65 73 73 61 67 65 73 20 77 68 65 6e 20 74 68 65  essages when the
0910: 79 20 77 65 72 65 20 75 73 65 64 2e 20 20 42 75  y were used.  Bu
0920: 74 20 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c  t that.** compil
0930: 65 72 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75  er magic ended u
0940: 70 20 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63  p generating suc
0950: 68 20 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75  h a flurry of bu
0960: 67 20 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61  g reports.** tha
0970: 74 20 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20  t we have taken 
0980: 69 74 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67  it all out and g
0990: 6f 6e 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e  one back to usin
09a0: 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70  g simple.** noop
09b0: 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66   macros..*/.#def
09c0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45  ine SQLITE_DEPRE
09d0: 43 41 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51  CATED.#define SQ
09e0: 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
09f0: 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20  L../*.** Ensure 
0a00: 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65  these symbols we
0a10: 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62  re not defined b
0a20: 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20  y some previous 
0a30: 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a  header file..*/.
0a40: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45  #ifdef SQLITE_VE
0a50: 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51  RSION.# undef SQ
0a60: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e  LITE_VERSION.#en
0a70: 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54  dif.#ifdef SQLIT
0a80: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0a90: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
0aa0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0ab0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
0ac0: 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
0ad0: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
0ae0: 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31 30  ion Numbers {H10
0af0: 30 31 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a  010} <S60100>.**
0b00: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56  .** The SQLITE_V
0b10: 45 52 53 49 4f 4e 20 61 6e 64 20 53 51 4c 49 54  ERSION and SQLIT
0b20: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0b30: 20 23 64 65 66 69 6e 65 73 20 69 6e 0a 2a 2a 20   #defines in.** 
0b40: 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 66 69  the sqlite3.h fi
0b50: 6c 65 20 73 70 65 63 69 66 79 20 74 68 65 20 76  le specify the v
0b60: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
0b70: 20 77 69 74 68 20 77 68 69 63 68 0a 2a 2a 20 74   with which.** t
0b80: 68 61 74 20 68 65 61 64 65 72 20 66 69 6c 65 20  hat header file 
0b90: 69 73 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a  is associated..*
0ba0: 2a 0a 2a 2a 20 54 68 65 20 22 76 65 72 73 69 6f  *.** The "versio
0bb0: 6e 22 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  n" of SQLite is 
0bc0: 61 20 73 74 72 69 6e 67 20 6f 66 20 74 68 65 20  a string of the 
0bd0: 66 6f 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a 2a 2a  form "X.Y.Z"..**
0be0: 20 54 68 65 20 70 68 72 61 73 65 20 22 61 6c 70   The phrase "alp
0bf0: 68 61 22 20 6f 72 20 22 62 65 74 61 22 20 6d 69  ha" or "beta" mi
0c00: 67 68 74 20 62 65 20 61 70 70 65 6e 64 65 64 20  ght be appended 
0c10: 61 66 74 65 72 20 74 68 65 20 5a 2e 0a 2a 2a 20  after the Z..** 
0c20: 54 68 65 20 58 20 76 61 6c 75 65 20 69 73 20 6d  The X value is m
0c30: 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ajor version num
0c40: 62 65 72 20 61 6c 77 61 79 73 20 33 20 69 6e 20  ber always 3 in 
0c50: 53 51 4c 69 74 65 33 2e 0a 2a 2a 20 54 68 65 20  SQLite3..** The 
0c60: 58 20 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61  X value only cha
0c70: 6e 67 65 73 20 77 68 65 6e 20 62 61 63 6b 77 61  nges when backwa
0c80: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
0c90: 79 20 69 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61  y is.** broken a
0ca0: 6e 64 20 77 65 20 69 6e 74 65 6e 64 20 74 6f 20  nd we intend to 
0cb0: 6e 65 76 65 72 20 62 72 65 61 6b 20 62 61 63 6b  never break back
0cc0: 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
0cd0: 69 74 79 2e 0a 2a 2a 20 54 68 65 20 59 20 76 61  ity..** The Y va
0ce0: 6c 75 65 20 69 73 20 74 68 65 20 6d 69 6e 6f 72  lue is the minor
0cf0: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
0d00: 61 6e 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73  and only changes
0d10: 20 77 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61   when.** there a
0d20: 72 65 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 65  re major feature
0d30: 20 65 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 68   enhancements th
0d40: 61 74 20 61 72 65 20 66 6f 72 77 61 72 64 73 20  at are forwards 
0d50: 63 6f 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75  compatible.** bu
0d60: 74 20 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 20  t not backwards 
0d70: 63 6f 6d 70 61 74 69 62 6c 65 2e 0a 2a 2a 20 54  compatible..** T
0d80: 68 65 20 5a 20 76 61 6c 75 65 20 69 73 20 74 68  he Z value is th
0d90: 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72  e release number
0da0: 20 61 6e 64 20 69 73 20 69 6e 63 72 65 6d 65 6e   and is incremen
0db0: 74 65 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 68  ted with.** each
0dc0: 20 72 65 6c 65 61 73 65 20 62 75 74 20 72 65 73   release but res
0dd0: 65 74 73 20 62 61 63 6b 20 74 6f 20 30 20 77 68  ets back to 0 wh
0de0: 65 6e 65 76 65 72 20 59 20 69 73 20 69 6e 63 72  enever Y is incr
0df0: 65 6d 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53  emented..**.** S
0e00: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
0e10: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20  3_libversion()] 
0e20: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  and [sqlite3_lib
0e30: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
0e40: 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
0e50: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30  NTS:.**.** {H100
0e60: 31 31 7d 20 54 68 65 20 53 51 4c 49 54 45 5f 56  11} The SQLITE_V
0e70: 45 52 53 49 4f 4e 20 23 64 65 66 69 6e 65 20 69  ERSION #define i
0e80: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20  n the sqlite3.h 
0e90: 68 65 61 64 65 72 20 66 69 6c 65 20 73 68 61 6c  header file shal
0ea0: 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 76  l.**          ev
0eb0: 61 6c 75 61 74 65 20 74 6f 20 61 20 73 74 72 69  aluate to a stri
0ec0: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0ed0: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0ee0: 72 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  rsion.**        
0ef0: 20 20 77 69 74 68 20 77 68 69 63 68 20 74 68 65    with which the
0f00: 20 68 65 61 64 65 72 20 66 69 6c 65 20 69 73 20   header file is 
0f10: 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a  associated..**.*
0f20: 2a 20 7b 48 31 30 30 31 34 7d 20 54 68 65 20 53  * {H10014} The S
0f30: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0f40: 4d 42 45 52 20 23 64 65 66 69 6e 65 20 73 68 61  MBER #define sha
0f50: 6c 6c 20 72 65 73 6f 6c 76 65 20 74 6f 20 61 6e  ll resolve to an
0f60: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20   integer.**     
0f70: 20 20 20 20 20 77 69 74 68 20 74 68 65 20 76 61       with the va
0f80: 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b  lue (X*1000000 +
0f90: 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65   Y*1000 + Z) whe
0fa0: 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 0a 2a  re X, Y, and Z.*
0fb0: 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 74  *          are t
0fc0: 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e  he major version
0fd0: 2c 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 2c  , minor version,
0fe0: 20 61 6e 64 20 72 65 6c 65 61 73 65 20 6e 75 6d   and release num
0ff0: 62 65 72 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ber..*/.#define 
1000: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20  SQLITE_VERSION  
1010: 20 20 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d         "--VERS--
1020: 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ".#define SQLITE
1030: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
1040: 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45   --VERSION-NUMBE
1050: 52 2d 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  R--../*.** CAPI3
1060: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
1070: 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75  brary Version Nu
1080: 6d 62 65 72 73 20 7b 48 31 30 30 32 30 7d 20 3c  mbers {H10020} <
1090: 53 36 30 31 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S60100>.** KEYWO
10a0: 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72  RDS: sqlite3_ver
10b0: 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sion.**.** These
10c0: 20 66 65 61 74 75 72 65 73 20 70 72 6f 76 69 64   features provid
10d0: 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  e the same infor
10e0: 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53  mation as the [S
10f0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a  QLITE_VERSION].*
1100: 2a 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 56 45  * and [SQLITE_VE
1110: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 23 64  RSION_NUMBER] #d
1120: 65 66 69 6e 65 73 20 69 6e 20 74 68 65 20 68 65  efines in the he
1130: 61 64 65 72 2c 20 62 75 74 20 61 72 65 20 61 73  ader, but are as
1140: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
1150: 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73   the library ins
1160: 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64  tead of the head
1170: 65 72 20 66 69 6c 65 2e 20 20 43 61 75 74 69 6f  er file.  Cautio
1180: 75 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  us programmers m
1190: 69 67 68 74 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  ight.** include 
11a0: 61 20 63 68 65 63 6b 20 69 6e 20 74 68 65 69 72  a check in their
11b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
11c0: 76 65 72 69 66 79 20 74 68 61 74 0a 2a 2a 20 73  verify that.** s
11d0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
11e0: 6e 5f 6e 75 6d 62 65 72 28 29 20 61 6c 77 61 79  n_number() alway
11f0: 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  s returns the va
1200: 6c 75 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56  lue.** [SQLITE_V
1210: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a  ERSION_NUMBER]..
1220: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1230: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
1240: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1250: 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
1260: 74 69 6f 6e 20 61 73 20 69 73 0a 2a 2a 20 69 6e  tion as is.** in
1270: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72   the sqlite3_ver
1280: 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f  sion[] string co
1290: 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 66 75 6e  nstant.  The fun
12a0: 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65  ction is provide
12b0: 64 0a 2a 2a 20 66 6f 72 20 75 73 65 20 69 6e 20  d.** for use in 
12c0: 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75  DLLs since DLL u
12d0: 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20  sers usually do 
12e0: 6e 6f 74 20 68 61 76 65 20 64 69 72 65 63 74 20  not have direct 
12f0: 61 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67  access to string
1300: 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 77 69  .** constants wi
1310: 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 0a 2a 2a  thin the DLL..**
1320: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1330: 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 31 7d 20 54  **.** {H10021} T
1340: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  he [sqlite3_libv
1350: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d  ersion_number()]
1360: 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c   interface shall
1370: 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20   return.**      
1380: 20 20 20 20 61 6e 20 69 6e 74 65 67 65 72 20 65      an integer e
1390: 71 75 61 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f  qual to [SQLITE_
13a0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e  VERSION_NUMBER].
13b0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 32 7d 20  .**.** {H10022} 
13c0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72  The [sqlite3_ver
13d0: 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e  sion] string con
13e0: 73 74 61 6e 74 20 73 68 61 6c 6c 20 63 6f 6e 74  stant shall cont
13f0: 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ain.**          
1400: 74 68 65 20 74 65 78 74 20 6f 66 20 74 68 65 20  the text of the 
1410: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
1420: 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
1430: 48 31 30 30 32 33 7d 20 54 68 65 20 5b 73 71 6c  H10023} The [sql
1440: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1450: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c  )] function shal
1460: 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  l return.**     
1470: 20 20 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74       a pointer t
1480: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
1490: 65 72 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63  ersion] string c
14a0: 6f 6e 73 74 61 6e 74 2e 0a 2a 2f 0a 53 51 4c 49  onstant..*/.SQLI
14b0: 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20  TE_EXTERN const 
14c0: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72  char sqlite3_ver
14d0: 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68  sion[];.const ch
14e0: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76  ar *sqlite3_libv
14f0: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e  ersion(void);.in
1500: 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  t sqlite3_libver
1510: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64  sion_number(void
1520: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1530: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20  EF: Test To See 
1540: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49  If The Library I
1550: 73 20 54 68 72 65 61 64 73 61 66 65 20 7b 48 31  s Threadsafe {H1
1560: 30 31 30 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a  0100} <S60100>.*
1570: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20  *.** SQLite can 
1580: 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  be compiled with
1590: 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65   or without mute
15a0: 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68  xes.  When.** th
15b0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
15c0: 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65  SAFE] C preproce
15d0: 73 73 6f 72 20 6d 61 63 72 6f 20 31 20 6f 72 20  ssor macro 1 or 
15e0: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
15f0: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
1600: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
1610: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
1620: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1630: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
1640: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
1650: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
1660: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
1670: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
1680: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
1690: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
16a0: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
16b0: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
16c0: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
16d0: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
16e0: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
16f0: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
1700: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
1710: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
1720: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
1730: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
1740: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
1750: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
1760: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
1770: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
1780: 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  ..** The default
1790: 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72   behavior is for
17a0: 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65   mutexes to be e
17b0: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  nabled..**.** Th
17c0: 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
17d0: 20 62 65 20 75 73 65 64 20 62 79 20 61 20 70 72   be used by a pr
17e0: 6f 67 72 61 6d 20 74 6f 20 6d 61 6b 65 20 73 75  ogram to make su
17f0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1800: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1810: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1820: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1830: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1840: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1850: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1860: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1870: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1880: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1890: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
18a0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
18b0: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
18c0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
18d0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
18e0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
18f0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1900: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1910: 31 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61  1 then mutexes a
1920: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
1930: 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e  fault but.** can
1940: 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72   be fully or par
1950: 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20  tially disabled 
1960: 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  using a call to 
1970: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
1980: 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76  )].** with the v
1990: 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  erbs [SQLITE_CON
19a0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
19b0: 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ], [SQLITE_CONFI
19c0: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a  G_MULTITHREAD],.
19d0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  ** or [SQLITE_CO
19e0: 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 54 68  NFIG_MUTEX].  Th
19f0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
1a00: 66 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  f this function 
1a10: 73 68 6f 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74 68  shows.** only th
1a20: 65 20 64 65 66 61 75 6c 74 20 63 6f 6d 70 69 6c  e default compil
1a30: 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 2c 20  e-time setting, 
1a40: 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65  not any run-time
1a50: 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 74   changes.** to t
1a60: 68 61 74 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  hat setting..**.
1a70: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
1a80: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
1a90: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
1aa0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
1ab0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  tion..**.** INVA
1ac0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
1ad0: 31 30 31 30 31 7d 20 54 68 65 20 5b 73 71 6c 69  10101} The [sqli
1ae0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
1af0: 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c  ] function shall
1b00: 20 72 65 74 75 72 6e 20 7a 65 72 6f 20 69 66 0a   return zero if.
1b10: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  **          and 
1b20: 6f 6e 6c 79 20 69 66 20 53 51 4c 69 74 65 20 77  only if SQLite w
1b30: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1b40: 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f   mutexing code o
1b50: 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  mitted..**.** {H
1b60: 31 30 31 30 32 7d 20 54 68 65 20 76 61 6c 75 65  10102} The value
1b70: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1b80: 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
1b90: 73 61 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e  safe()] function
1ba0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61  .**          sha
1bb0: 6c 6c 20 72 65 6d 61 69 6e 20 74 68 65 20 73 61  ll remain the sa
1bc0: 6d 65 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20  me across calls 
1bd0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  to [sqlite3_conf
1be0: 69 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ig()]..*/.int sq
1bf0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
1c00: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
1c10: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
1c20: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e  e Connection Han
1c30: 64 6c 65 20 7b 48 31 32 30 30 30 7d 20 3c 53 34  dle {H12000} <S4
1c40: 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0200>.** KEYWORD
1c50: 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  S: {database con
1c60: 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61  nection} {databa
1c70: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a  se connections}.
1c80: 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20  **.** Each open 
1c90: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
1ca0: 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  is represented b
1cb0: 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  y a pointer to a
1cc0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a  n instance of.**
1cd0: 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75   the opaque stru
1ce0: 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c  cture named "sql
1cf0: 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73  ite3".  It is us
1d00: 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66  eful to think of
1d10: 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70   an sqlite3.** p
1d20: 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a  ointer as an obj
1d30: 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ect.  The [sqlit
1d40: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
1d50: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
1d60: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1d70: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
1d80: 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f  faces are its co
1d90: 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20  nstructors, and 
1da0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
1db0: 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64 65 73 74  ].** is its dest
1dc0: 72 75 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61  ructor.  There a
1dd0: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e  re many other in
1de0: 74 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61  terfaces (such a
1df0: 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  s.** [sqlite3_pr
1e00: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
1e10: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
1e20: 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a  ction()], and.**
1e30: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
1e40: 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d  imeout()] to nam
1e50: 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61  e but three) tha
1e60: 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e  t are methods on
1e70: 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f   an.** sqlite3 o
1e80: 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65  bject..*/.typede
1e90: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
1ea0: 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a   sqlite3;../*.**
1eb0: 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69   CAPI3REF: 64-Bi
1ec0: 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 20  t Integer Types 
1ed0: 7b 48 31 30 32 30 30 7d 20 3c 53 31 30 31 31 30  {H10200} <S10110
1ee0: 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  >.** KEYWORDS: s
1ef0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
1f00: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
1f10: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
1f20: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
1f30: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
1f40: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
1f50: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
1f60: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
1f70: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
1f80: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
1f90: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
1fa0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
1fb0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
1fc0: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
1fd0: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
1fe0: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
1ff0: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
2000: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
2010: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
2020: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
2030: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
2040: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
2050: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2060: 2a 20 7b 48 31 30 32 30 31 7d 20 54 68 65 20 5b  * {H10201} The [
2070: 73 71 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e  sqlite_int64] an
2080: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d [sqlite3_int64
2090: 5d 20 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65  ] type shall spe
20a0: 63 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  cify.**         
20b0: 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64   a 64-bit signed
20c0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
20d0: 7b 48 31 30 32 30 32 7d 20 54 68 65 20 5b 73 71  {H10202} The [sq
20e0: 6c 69 74 65 5f 75 69 6e 74 36 34 5d 20 61 6e 64  lite_uint64] and
20f0: 20 5b 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34   [sqlite3_uint64
2100: 5d 20 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65  ] type shall spe
2110: 63 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  cify.**         
2120: 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e   a 64-bit unsign
2130: 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23  ed integer..*/.#
2140: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2150: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2160: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2170: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2180: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
2190: 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36  gned SQLITE_INT6
21a0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69  4_TYPE sqlite_ui
21b0: 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69  nt64;.#elif defi
21c0: 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c  ned(_MSC_VER) ||
21d0: 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41   defined(__BORLA
21e0: 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66  NDC__).  typedef
21f0: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f   __int64 sqlite_
2200: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
2210: 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36   unsigned __int6
2220: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  4 sqlite_uint64;
2230: 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66  .#else.  typedef
2240: 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73   long long int s
2250: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
2260: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
2270: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71  long long int sq
2280: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e  lite_uint64;.#en
2290: 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69  dif.typedef sqli
22a0: 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  te_int64 sqlite3
22b0: 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20  _int64;.typedef 
22c0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71  sqlite_uint64 sq
22d0: 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f  lite3_uint64;../
22e0: 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e  *.** If compilin
22f0: 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f  g for a processo
2300: 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f  r that lacks flo
2310: 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70  ating point supp
2320: 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75  ort,.** substitu
2330: 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66  te integer for f
2340: 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a  loating-point..*
2350: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
2360: 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f  OMIT_FLOATING_PO
2370: 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75  INT.# define dou
2380: 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  ble sqlite3_int6
2390: 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  4.#endif../*.** 
23a0: 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e  CAPI3REF: Closin
23b0: 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e  g A Database Con
23c0: 6e 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d  nection {H12010}
23d0: 20 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30   <S30100><S40200
23e0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  >.**.** This rou
23f0: 74 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74  tine is the dest
2400: 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b  ructor for the [
2410: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e  sqlite3] object.
2420: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2430: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69  ons should [sqli
2440: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
2450: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72  inalize] all [pr
2460: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2470: 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  s].** and [sqlit
2480: 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20  e3_blob_close | 
2490: 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42  close] all [BLOB
24a0: 20 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69   handles] associ
24b0: 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  ated with.** the
24c0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
24d0: 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d  t prior to attem
24e0: 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74  pting to close t
24f0: 68 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68  he object..** Th
2500: 65 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  e [sqlite3_next_
2510: 73 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63  stmt()] interfac
2520: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
2530: 20 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b   locate all.** [
2540: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2550: 6e 74 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20  nts] associated 
2560: 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
2570: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20   connection] if 
2580: 64 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69  desired..** Typi
2590: 63 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c  cal code might l
25a0: 6f 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ook like this:.*
25b0: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
25c0: 3e 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65  ><pre>.** sqlite
25d0: 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a  3_stmt *pStmt;.*
25e0: 2a 20 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20  * while( (pStmt 
25f0: 3d 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73  = sqlite3_next_s
2600: 74 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29  tmt(db, 0))!=0 )
2610: 7b 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71  {.** &nbsp;   sq
2620: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70  lite3_finalize(p
2630: 53 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c  Stmt);.** }.** <
2640: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
2650: 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c  e>.**.** If [sql
2660: 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73  ite3_close()] is
2670: 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61   invoked while a
2680: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2690: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61  open,.** the tra
26a0: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
26b0: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
26c0: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   back..**.** INV
26d0: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
26e0: 48 31 32 30 31 31 7d 20 41 20 73 75 63 63 65 73  H12011} A succes
26f0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
2700: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20  lite3_close(C)] 
2710: 73 68 61 6c 6c 20 64 65 73 74 72 6f 79 20 74 68  shall destroy th
2720: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  e.**          [d
2730: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2740: 6f 6e 5d 20 6f 62 6a 65 63 74 20 43 2e 0a 2a 2a  on] object C..**
2750: 0a 2a 2a 20 7b 48 31 32 30 31 32 7d 20 41 20 73  .** {H12012} A s
2760: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
2770: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
2780: 28 43 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 72  (C)] shall retur
2790: 6e 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a  n SQLITE_OK..**.
27a0: 2a 2a 20 7b 48 31 32 30 31 33 7d 20 41 20 73 75  ** {H12013} A su
27b0: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
27c0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
27d0: 43 29 5d 20 73 68 61 6c 6c 20 72 65 6c 65 61 73  C)] shall releas
27e0: 65 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  e all.**        
27f0: 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20 73 79 73    memory and sys
2800: 74 65 6d 20 72 65 73 6f 75 72 63 65 73 20 61 73  tem resources as
2810: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b 64  sociated with [d
2820: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2830: 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  on].**          
2840: 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 34  C..**.** {H12014
2850: 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  } A call to [sql
2860: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6f  ite3_close(C)] o
2870: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  n a [database co
2880: 6e 6e 65 63 74 69 6f 6e 5d 20 43 20 74 68 61 74  nnection] C that
2890: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 73  .**          has
28a0: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 70 65   one or more ope
28b0: 6e 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  n [prepared stat
28c0: 65 6d 65 6e 74 73 5d 20 73 68 61 6c 6c 20 66 61  ements] shall fa
28d0: 69 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20  il with.**      
28e0: 20 20 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42      an [SQLITE_B
28f0: 55 53 59 5d 20 65 72 72 6f 72 20 63 6f 64 65 2e  USY] error code.
2900: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 35 7d 20  .**.** {H12015} 
2910: 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
2920: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 77 68 65  e3_close(C)] whe
2930: 72 65 20 43 20 69 73 20 61 20 4e 55 4c 4c 20 70  re C is a NULL p
2940: 6f 69 6e 74 65 72 20 73 68 61 6c 6c 0a 2a 2a 20  ointer shall.** 
2950: 20 20 20 20 20 20 20 20 20 62 65 20 61 20 68 61           be a ha
2960: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 20 72 65 74  rmless no-op ret
2970: 75 72 6e 69 6e 67 20 53 51 4c 49 54 45 5f 4f 4b  urning SQLITE_OK
2980: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 39 7d  ..**.** {H12019}
2990: 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 63   When [sqlite3_c
29a0: 6c 6f 73 65 28 43 29 5d 20 69 73 20 69 6e 76 6f  lose(C)] is invo
29b0: 6b 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61  ked on a [databa
29c0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 43  se connection] C
29d0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61  .**          tha
29e0: 74 20 68 61 73 20 61 20 70 65 6e 64 69 6e 67 20  t has a pending 
29f0: 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
2a00: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 73 68 61   transaction sha
2a10: 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20  ll be.**        
2a20: 20 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a    rolled back..*
2a30: 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
2a40: 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 30 31 36 7d  :.**.** {A12016}
2a50: 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65 72   The C parameter
2a60: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
2a70: 73 65 28 43 29 5d 20 6d 75 73 74 20 62 65 20 65  se(C)] must be e
2a80: 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  ither a NULL.** 
2a90: 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72           pointer
2aa0: 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d   or an [sqlite3]
2ab0: 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20   object pointer 
2ac0: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 20 20 20 20  obtained.**     
2ad0: 20 20 20 20 20 66 72 6f 6d 20 5b 73 71 6c 69 74       from [sqlit
2ae0: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
2af0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
2b00: 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
2b10: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2b20: 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76  )], and not prev
2b30: 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a  iously closed..*
2b40: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
2b50: 6f 73 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a  ose(sqlite3 *);.
2b60: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20  ./*.** The type 
2b70: 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  for a callback f
2b80: 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73  unction..** This
2b90: 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64   is legacy and d
2ba0: 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69  eprecated.  It i
2bb0: 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68  s included for h
2bc0: 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d  istorical.** com
2bd0: 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69  patibility and i
2be0: 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64  s not documented
2bf0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74  ..*/.typedef int
2c00: 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62   (*sqlite3_callb
2c10: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
2c20: 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a  har**, char**);.
2c30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c40: 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20   One-Step Query 
2c50: 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66  Execution Interf
2c60: 61 63 65 20 7b 48 31 32 31 30 30 7d 20 3c 53 31  ace {H12100} <S1
2c70: 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0000>.**.** The 
2c80: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
2c90: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
2ca0: 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 6f 66 20  nvenient way of 
2cb0: 72 75 6e 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d  running one or m
2cc0: 6f 72 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ore.** SQL state
2cd0: 6d 65 6e 74 73 20 77 69 74 68 6f 75 74 20 68 61  ments without ha
2ce0: 76 69 6e 67 20 74 6f 20 77 72 69 74 65 20 61 20  ving to write a 
2cf0: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 20  lot of C code.  
2d00: 54 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  The UTF-8 encode
2d10: 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
2d20: 6e 74 73 20 61 72 65 20 70 61 73 73 65 64 20 69  nts are passed i
2d30: 6e 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  n as the second 
2d40: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2d50: 69 74 65 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20  ite3_exec()..** 
2d60: 54 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 61  The statements a
2d70: 72 65 20 65 76 61 6c 75 61 74 65 64 20 6f 6e 65  re evaluated one
2d80: 20 62 79 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69   by one until ei
2d90: 74 68 65 72 20 61 6e 20 65 72 72 6f 72 20 6f 72  ther an error or
2da0: 0a 2a 2a 20 61 6e 20 69 6e 74 65 72 72 75 70 74  .** an interrupt
2db0: 20 69 73 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c   is encountered,
2dc0: 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 79 20 61   or until they a
2dd0: 72 65 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68  re all done.  Th
2de0: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 0a  e 3rd parameter.
2df0: 2a 2a 20 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61  ** is an optiona
2e00: 6c 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20  l callback that 
2e10: 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20  is invoked once 
2e20: 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20  for each row of 
2e30: 61 6e 79 20 71 75 65 72 79 0a 2a 2a 20 72 65 73  any query.** res
2e40: 75 6c 74 73 20 70 72 6f 64 75 63 65 64 20 62 79  ults produced by
2e50: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2e60: 6e 74 73 2e 20 20 54 68 65 20 35 74 68 20 70 61  nts.  The 5th pa
2e70: 72 61 6d 65 74 65 72 20 74 65 6c 6c 73 20 77 68  rameter tells wh
2e80: 65 72 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20  ere.** to write 
2e90: 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67  any error messag
2ea0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72  es..**.** The er
2eb0: 72 6f 72 20 6d 65 73 73 61 67 65 20 70 61 73 73  ror message pass
2ec0: 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20  ed back through 
2ed0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
2ee0: 72 20 69 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20  r is held.** in 
2ef0: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
2f00: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2f10: 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f  lloc()].  To avo
2f20: 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b  id a memory leak
2f30: 2c 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67  ,.** the calling
2f40: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
2f50: 75 6c 64 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  uld call [sqlite
2f60: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79  3_free()] on any
2f70: 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
2f80: 65 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  e returned throu
2f90: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
2fa0: 65 74 65 72 20 77 68 65 6e 20 69 74 20 68 61 73  eter when it has
2fb0: 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a   finished using.
2fc0: 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ** the error mes
2fd0: 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  sage..**.** If t
2fe0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2ff0: 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61   in the 2nd para
3000: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72  meter is NULL or
3010: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
3020: 0a 2a 2a 20 6f 72 20 61 20 73 74 72 69 6e 67 20  .** or a string 
3030: 63 6f 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20  containing only 
3040: 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 20 63  whitespace and c
3050: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f  omments, then no
3060: 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
3070: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
3080: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
3090: 65 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  e is not changed
30a0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
30b0: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
30c0: 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
30d0: 74 65 64 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a  ted in terms of.
30e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
30f0: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
3100: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64  te3_step()], and
3110: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
3120: 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71  ze()]..** The sq
3130: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 72 6f 75  lite3_exec() rou
3140: 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e  tine does nothin
3150: 67 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  g to the databas
3160: 65 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65  e that cannot be
3170: 20 64 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c   done.** by [sql
3180: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
3190: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
31a0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
31b0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
31c0: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
31d0: 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 31 7d  :.**.** {H12101}
31e0: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
31f0: 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
3200: 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c  ite3_exec(D,S,C,
3210: 41 2c 45 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  A,E)].**        
3220: 20 20 73 68 61 6c 6c 20 73 65 71 75 65 6e 74 69    shall sequenti
3230: 61 6c 6c 79 20 65 76 61 6c 75 61 74 65 20 61 6c  ally evaluate al
3240: 6c 20 6f 66 20 74 68 65 20 55 54 46 2d 38 20 65  l of the UTF-8 e
3250: 6e 63 6f 64 65 64 2c 0a 2a 2a 20 20 20 20 20 20  ncoded,.**      
3260: 20 20 20 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65      semicolon-se
3270: 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
3280: 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
3290: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
32a0: 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
32b0: 20 53 20 77 69 74 68 69 6e 20 74 68 65 20 63 6f   S within the co
32c0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
32d0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
32e0: 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  n] D..**.** {H12
32f0: 31 30 32 7d 20 49 66 20 74 68 65 20 53 20 70 61  102} If the S pa
3300: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
3310: 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41  te3_exec(D,S,C,A
3320: 2c 45 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65  ,E)] is NULL the
3330: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
3340: 65 20 61 63 74 69 6f 6e 73 20 6f 66 20 74 68 65  e actions of the
3350: 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c   interface shall
3360: 20 62 65 20 74 68 65 20 73 61 6d 65 20 61 73 20   be the same as 
3370: 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  if the.**       
3380: 20 20 20 53 20 70 61 72 61 6d 65 74 65 72 20 77     S parameter w
3390: 65 72 65 20 61 6e 20 65 6d 70 74 79 20 73 74 72  ere an empty str
33a0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31  ing..**.** {H121
33b0: 30 34 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76  04} The return v
33c0: 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
33d0: 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62  _exec()] shall b
33e0: 65 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66  e [SQLITE_OK] if
33f0: 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20   all.**         
3400: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
3410: 72 75 6e 20 73 75 63 63 65 73 73 66 75 6c 6c 79  run successfully
3420: 20 61 6e 64 20 74 6f 20 63 6f 6d 70 6c 65 74 69   and to completi
3430: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30  on..**.** {H1210
3440: 35 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  5} The return va
3450: 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
3460: 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65  exec()] shall be
3470: 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a   an appropriate.
3480: 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 6e 2d  **          non-
3490: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
34a0: 5d 20 69 66 20 61 6e 79 20 53 51 4c 20 73 74 61  ] if any SQL sta
34b0: 74 65 6d 65 6e 74 20 66 61 69 6c 73 2e 0a 2a 2a  tement fails..**
34c0: 0a 2a 2a 20 7b 48 31 32 31 30 37 7d 20 49 66 20  .** {H12107} If 
34d0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
34e0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
34f0: 73 20 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c  s handed to [sql
3500: 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20  ite3_exec()].** 
3510: 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
3520: 72 65 73 75 6c 74 73 20 61 6e 64 20 74 68 65 20  results and the 
3530: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  3rd parameter is
3540: 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a   not NULL, then.
3550: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
3560: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3570: 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  n specified by t
3580: 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
3590: 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20   shall be.**    
35a0: 20 20 20 20 20 20 69 6e 76 6f 6b 65 64 20 6f 6e        invoked on
35b0: 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20  ce for each row 
35c0: 6f 66 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a  of result..**.**
35d0: 20 7b 48 31 32 31 31 30 7d 20 49 66 20 74 68 65   {H12110} If the
35e0: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
35f0: 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c  s a non-zero val
3600: 75 65 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ue then [sqlite3
3610: 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20  _exec()].**     
3620: 20 20 20 20 20 73 68 61 6c 6c 20 61 62 6f 72 74       shall abort
3630: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3640: 6e 74 20 69 74 20 69 73 20 63 75 72 72 65 6e 74  nt it is current
3650: 6c 79 20 65 76 61 6c 75 61 74 69 6e 67 2c 0a 2a  ly evaluating,.*
3660: 2a 20 20 20 20 20 20 20 20 20 20 73 6b 69 70 20  *          skip 
3670: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 53  all subsequent S
3680: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61  QL statements, a
3690: 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
36a0: 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20  E_ABORT]..**.** 
36b0: 7b 48 31 32 31 31 33 7d 20 54 68 65 20 5b 73 71  {H12113} The [sq
36c0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f  lite3_exec()] ro
36d0: 75 74 69 6e 65 20 73 68 61 6c 6c 20 70 61 73 73  utine shall pass
36e0: 20 69 74 73 20 34 74 68 20 70 61 72 61 6d 65 74   its 4th paramet
36f0: 65 72 20 74 68 72 6f 75 67 68 0a 2a 2a 20 20 20  er through.**   
3700: 20 20 20 20 20 20 20 61 73 20 74 68 65 20 31 73         as the 1s
3710: 74 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  t parameter of t
3720: 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  he callback..**.
3730: 2a 2a 20 7b 48 31 32 31 31 36 7d 20 54 68 65 20  ** {H12116} The 
3740: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3750: 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73   routine shall s
3760: 65 74 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  et the 2nd param
3770: 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20  eter of its.**  
3780: 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b          callback
3790: 20 74 6f 20 62 65 20 74 68 65 20 6e 75 6d 62 65   to be the numbe
37a0: 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
37b0: 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
37c0: 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  of.**          r
37d0: 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  esult..**.** {H1
37e0: 32 31 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  2119} The [sqlit
37f0: 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69  e3_exec()] routi
3800: 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65  ne shall set the
3810: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 6f   3rd parameter o
3820: 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  f its.**        
3830: 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65    callback to be
3840: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3850: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3860: 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20   holding the.** 
3870: 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 73 20           values 
3880: 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20  for each column 
3890: 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
38a0: 65 73 75 6c 74 20 73 65 74 20 72 6f 77 20 61 73  esult set row as
38b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74  .**          obt
38c0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
38d0: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
38e0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 32  )]..**.** {H1212
38f0: 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
3900: 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20  exec()] routine 
3910: 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 34 74  shall set the 4t
3920: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69  h parameter of i
3930: 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  ts.**          c
3940: 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 61 6e  allback to be an
3950: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3960: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 68 6f  rs to strings ho
3970: 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20  lding the.**    
3980: 20 20 20 20 20 20 6e 61 6d 65 73 20 6f 66 20 72        names of r
3990: 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 61 73  esult columns as
39a0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
39b0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
39c0: 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ame()]..**.** {H
39d0: 31 32 31 32 35 7d 20 49 66 20 74 68 65 20 33 72  12125} If the 3r
39e0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
39f0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
3a00: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20  is NULL then.** 
3a10: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
3a20: 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20  3_exec()] shall 
3a30: 73 69 6c 65 6e 74 6c 79 20 64 69 73 63 61 72 64  silently discard
3a40: 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 0a   query results..
3a50: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 31 7d 20 49  **.** {H12131} I
3a60: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
3a70: 73 20 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20  s while parsing 
3a80: 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 61 6e  or evaluating an
3a90: 79 20 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20  y of the SQL.** 
3aa0: 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65           stateme
3ab0: 6e 74 73 20 69 6e 20 74 68 65 20 53 20 70 61 72  nts in the S par
3ac0: 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74  ameter of [sqlit
3ad0: 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c  e3_exec(D,S,C,A,
3ae0: 45 29 5d 20 61 6e 64 20 69 66 0a 2a 2a 20 20 20  E)] and if.**   
3af0: 20 20 20 20 20 20 20 74 68 65 20 45 20 70 61 72         the E par
3b00: 61 6d 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ameter is not NU
3b10: 4c 4c 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  LL, then [sqlite
3b20: 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20  3_exec()] shall 
3b30: 73 74 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20  store.**        
3b40: 20 20 69 6e 20 2a 45 20 61 6e 20 61 70 70 72 6f    in *E an appro
3b50: 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73  priate error mes
3b60: 73 61 67 65 20 77 72 69 74 74 65 6e 20 69 6e 74  sage written int
3b70: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
3b80: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72  d.**          fr
3b90: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3ba0: 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  oc()]..**.** {H1
3bb0: 32 31 33 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  2134} The [sqlit
3bc0: 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c  e3_exec(D,S,C,A,
3bd0: 45 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c  E)] routine shal
3be0: 6c 20 73 65 74 20 74 68 65 20 76 61 6c 75 65 20  l set the value 
3bf0: 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a  of.**          *
3c00: 45 20 74 6f 20 4e 55 4c 4c 20 69 66 20 45 20 69  E to NULL if E i
3c10: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 74  s not NULL and t
3c20: 68 65 72 65 20 61 72 65 20 6e 6f 20 65 72 72 6f  here are no erro
3c30: 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33  rs..**.** {H1213
3c40: 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
3c50: 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d  exec(D,S,C,A,E)]
3c60: 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
3c70: 73 65 74 20 74 68 65 20 5b 65 72 72 6f 72 20 63  set the [error c
3c80: 6f 64 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ode].**         
3c90: 20 61 6e 64 20 6d 65 73 73 61 67 65 20 61 63 63   and message acc
3ca0: 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c  essible via [sql
3cb0: 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c  ite3_errcode()],
3cc0: 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73   .**          [s
3cd0: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
3ce0: 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20  errcode()],.**  
3cf0: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
3d00: 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20  _errmsg()], and 
3d10: 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
3d20: 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  6()]..**.** {H12
3d30: 31 33 38 7d 20 49 66 20 74 68 65 20 53 20 70 61  138} If the S pa
3d40: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
3d50: 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41  te3_exec(D,S,C,A
3d60: 2c 45 29 5d 20 69 73 20 4e 55 4c 4c 20 6f 72 20  ,E)] is NULL or 
3d70: 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  an.**          e
3d80: 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 63  mpty string or c
3d90: 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20  ontains nothing 
3da0: 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 74 65  other than white
3db0: 73 70 61 63 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c  space, comments,
3dc0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
3dd0: 2f 6f 72 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c 20  /or semicolons, 
3de0: 74 68 65 6e 20 72 65 73 75 6c 74 73 20 6f 66 20  then results of 
3df0: 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
3e00: 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
3e10: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64   [sqlite3_extend
3e20: 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a  ed_errcode()],.*
3e30: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
3e40: 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61  te3_errmsg()], a
3e50: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  nd [sqlite3_errm
3e60: 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20  sg16()].**      
3e70: 20 20 20 20 73 68 61 6c 6c 20 72 65 73 65 74 20      shall reset 
3e80: 74 6f 20 69 6e 64 69 63 61 74 65 20 6e 6f 20 65  to indicate no e
3e90: 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 53 53  rrors..**.** ASS
3ea0: 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  UMPTIONS:.**.** 
3eb0: 7b 41 31 32 31 34 31 7d 20 54 68 65 20 66 69 72  {A12141} The fir
3ec0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
3ed0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3ee0: 20 6d 75 73 74 20 62 65 20 61 6e 20 76 61 6c 69   must be an vali
3ef0: 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20 20  d and open.**   
3f00: 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
3f10: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
3f20: 0a 2a 2a 20 7b 41 31 32 31 34 32 7d 20 54 68 65  .** {A12142} The
3f30: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
3f40: 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65  tion must not be
3f50: 20 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a   closed while.**
3f60: 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
3f70: 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75  e3_exec()] is ru
3f80: 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31  nning..**.** {A1
3f90: 32 31 34 33 7d 20 54 68 65 20 63 61 6c 6c 69 6e  2143} The callin
3fa0: 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  g function shoul
3fb0: 64 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 66  d use [sqlite3_f
3fc0: 72 65 65 28 29 5d 20 74 6f 20 66 72 65 65 0a 2a  ree()] to free.*
3fd0: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6d  *          the m
3fe0: 65 6d 6f 72 79 20 74 68 61 74 20 2a 65 72 72 6d  emory that *errm
3ff0: 73 67 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  sg is left point
4000: 69 6e 67 20 61 74 20 6f 6e 63 65 20 74 68 65 20  ing at once the 
4010: 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  error.**        
4020: 20 20 6d 65 73 73 61 67 65 20 69 73 20 6e 6f 20    message is no 
4030: 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a  longer needed..*
4040: 2a 0a 2a 2a 20 7b 41 31 32 31 34 35 7d 20 54 68  *.** {A12145} Th
4050: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
4060: 74 65 78 74 20 69 6e 20 74 68 65 20 32 6e 64 20  text in the 2nd 
4070: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
4080: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a  lite3_exec()].**
4090: 20 20 20 20 20 20 20 20 20 20 6d 75 73 74 20 72            must r
40a0: 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20  emain unchanged 
40b0: 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65  while [sqlite3_e
40c0: 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  xec()] is runnin
40d0: 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  g..*/.int sqlite
40e0: 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65  3_exec(.  sqlite
40f0: 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  3*,             
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
4120: 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
4130: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20  nst char *sql,  
4140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4150: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20           /* SQL 
4160: 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
4170: 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62  */.  int (*callb
4180: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
4190: 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20  har**,char**),  
41a0: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63  /* Callback func
41b0: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
41c0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75       /* 1st argu
41f0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b  ment to callback
4200: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72   */.  char **err
4210: 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20  msg             
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4230: 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
4240: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
4250: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4260: 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b  : Result Codes {
4270: 48 31 30 32 31 30 7d 20 3c 53 31 30 37 30 30 3e  H10210} <S10700>
4280: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
4290: 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63  LITE_OK {error c
42a0: 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65  ode} {error code
42b0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
42c0: 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72  {result code} {r
42d0: 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a  esult codes}.**.
42e0: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
42f0: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
4300: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
4310: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
4320: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72  set shown.** her
4330: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  e in order to in
4340: 64 69 63 61 74 65 73 20 73 75 63 63 65 73 73 20  dicates success 
4350: 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a  or failure..**.*
4360: 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65  * New error code
4370: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
4380: 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
4390: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
43a0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51  ** See also: [SQ
43b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
43c0: 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  | extended resul
43d0: 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66  t codes].*/.#def
43e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
43f0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
4400: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
4410: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
4420: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4430: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4440: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
4450: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
4460: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
4470: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
4480: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
4490: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e     2   /* Intern
44a0: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69  al logic error i
44b0: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66  n SQLite */.#def
44c0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20  ine SQLITE_PERM 
44d0: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41          3   /* A
44e0: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e  ccess permission
44f0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
4500: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ne SQLITE_ABORT 
4510: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61         4   /* Ca
4520: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
4530: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72  equested an abor
4540: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4550: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20  ITE_BUSY        
4560: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61   5   /* The data
4570: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63  base file is loc
4580: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
4590: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20  QLITE_LOCKED    
45a0: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c     6   /* A tabl
45b0: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  e in the databas
45c0: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
45d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
45e0: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f  MEM        7   /
45f0: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69  * A malloc() fai
4600: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  led */.#define S
4610: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20  QLITE_READONLY  
4620: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70     8   /* Attemp
4630: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61  t to write a rea
4640: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a  donly database *
4650: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4660: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20  _INTERRUPT    9 
4670: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74    /* Operation t
4680: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c  erminated by sql
4690: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
46a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
46b0: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30  E_IOERR       10
46c0: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20     /* Some kind 
46d0: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f  of disk I/O erro
46e0: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64  r occurred */.#d
46f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
4700: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a  RUPT     11   /*
4710: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69   The database di
4720: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66  sk image is malf
4730: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ormed */.#define
4740: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
4750: 20 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20      12   /* NOT 
4760: 55 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72  USED. Table or r
4770: 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20  ecord not found 
4780: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4790: 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33  E_FULL        13
47a0: 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20     /* Insertion 
47b0: 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64  failed because d
47c0: 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20  atabase is full 
47d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
47e0: 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34  E_CANTOPEN    14
47f0: 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20     /* Unable to 
4800: 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
4810: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4820: 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f  e SQLITE_PROTOCO
4830: 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54  L    15   /* NOT
4840: 20 55 53 45 44 2e 20 44 61 74 61 62 61 73 65 20   USED. Database 
4850: 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72  lock protocol er
4860: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
4870: 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20  QLITE_EMPTY     
4880: 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61    16   /* Databa
4890: 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23  se is empty */.#
48a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43  define SQLITE_SC
48b0: 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f  HEMA      17   /
48c0: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73  * The database s
48d0: 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f  chema changed */
48e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48f0: 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20  TOOBIG      18  
4900: 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c   /* String or BL
4910: 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20  OB exceeds size 
4920: 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65  limit */.#define
4930: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
4940: 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72  NT  19   /* Abor
4950: 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61  t due to constra
4960: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f  int violation */
4970: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4980: 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20  MISMATCH    20  
4990: 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69   /* Data type mi
49a0: 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e  smatch */.#defin
49b0: 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  e SQLITE_MISUSE 
49c0: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62       21   /* Lib
49d0: 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72  rary used incorr
49e0: 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ectly */.#define
49f0: 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20   SQLITE_NOLFS   
4a00: 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73      22   /* Uses
4a10: 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74   OS features not
4a20: 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f   supported on ho
4a30: 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  st */.#define SQ
4a40: 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20  LITE_AUTH       
4a50: 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69   23   /* Authori
4a60: 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  zation denied */
4a70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4a80: 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20  FORMAT      24  
4a90: 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61   /* Auxiliary da
4aa0: 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72  tabase format er
4ab0: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
4ac0: 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20  QLITE_RANGE     
4ad0: 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61    25   /* 2nd pa
4ae0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
4af0: 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72  e3_bind out of r
4b00: 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ange */.#define 
4b10: 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20  SQLITE_NOTADB   
4b20: 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20     26   /* File 
4b30: 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e  opened that is n
4b40: 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
4b50: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
4b60: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
4b70: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
4b80: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
4b90: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bb0: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4bc0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4bd0: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4be0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4bf0: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
4c00: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
4c10: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
4c20: 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31  Result Codes {H1
4c30: 30 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  0220} <S10700>.*
4c40: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74  * KEYWORDS: {ext
4c50: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
4c60: 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  } {extended erro
4c70: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
4c80: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
4c90: 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78  result code} {ex
4ca0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4cb0: 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74  des}.**.** In it
4cc0: 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  s default config
4cd0: 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20  uration, SQLite 
4ce0: 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74  API routines ret
4cf0: 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e  urn one of 26 in
4d00: 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  teger.** [SQLITE
4d10: 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64  _OK | result cod
4d20: 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65  es].  However, e
4d30: 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68  xperience has sh
4d40: 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66  own that many of
4d50: 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74  .** these result
4d60: 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63   codes are too c
4d70: 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20  oarse-grained.  
4d80: 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76  They do not prov
4d90: 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69  ide as.** much i
4da0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
4db0: 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f   problems as pro
4dc0: 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c  grammers might l
4dd0: 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f  ike.  In an effo
4de0: 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73  rt to.** address
4df0: 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72   this, newer ver
4e00: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
4e10: 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61  (version 3.3.8 a
4e20: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64  nd later) includ
4e30: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72  e.** support for
4e40: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75   additional resu
4e50: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72  lt codes that pr
4e60: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69  ovide more detai
4e70: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  led information.
4e80: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e  ** about errors.
4e90: 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65   The extended re
4ea0: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65  sult codes are e
4eb0: 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
4ec0: 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64  ed.** on a per d
4ed0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
4ee0: 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74  on basis using t
4ef0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
4f00: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
4f10: 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a  odes()] API..**.
4f20: 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61  ** Some of the a
4f30: 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65  vailable extende
4f40: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
4f50: 72 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a  re listed here..
4f60: 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63  ** One may expec
4f70: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
4f80: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4f90: 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78  codes will be ex
4fa0: 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d  pand.** over tim
4fb0: 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  e.  Software tha
4fc0: 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20  t uses extended 
4fd0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f  result codes sho
4fe0: 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f  uld expect.** to
4ff0: 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20   see new result 
5000: 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20  codes in future 
5010: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
5020: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  te..**.** The SQ
5030: 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63  LITE_OK result c
5040: 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62  ode will never b
5050: 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20  e extended.  It 
5060: 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62  will always.** b
5070: 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a  e exactly zero..
5080: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
5090: 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 33 7d  :.**.** {H10223}
50a0: 20 54 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61   The symbolic na
50b0: 6d 65 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64  me for an extend
50c0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 73  ed result code s
50d0: 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  hall contains.**
50e0: 20 20 20 20 20 20 20 20 20 20 61 20 72 65 6c 61            a rela
50f0: 74 65 64 20 70 72 69 6d 61 72 79 20 72 65 73 75  ted primary resu
5100: 6c 74 20 63 6f 64 65 20 61 73 20 61 20 70 72 65  lt code as a pre
5110: 66 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32  fix..**.** {H102
5120: 32 34 7d 20 50 72 69 6d 61 72 79 20 72 65 73 75  24} Primary resu
5130: 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68  lt code names sh
5140: 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 61 20 73 69  all contain a si
5150: 6e 67 6c 65 20 22 5f 22 20 63 68 61 72 61 63 74  ngle "_" charact
5160: 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32  er..**.** {H1022
5170: 35 7d 20 45 78 74 65 6e 64 65 64 20 72 65 73 75  5} Extended resu
5180: 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68  lt code names sh
5190: 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20  all contain two 
51a0: 6f 72 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72  or more "_" char
51b0: 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  acters..**.** {H
51c0: 31 30 32 32 36 7d 20 54 68 65 20 6e 75 6d 65 72  10226} The numer
51d0: 69 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65  ic value of an e
51e0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
51f0: 6f 64 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69  ode shall contai
5200: 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
5210: 20 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20    numeric value 
5220: 6f 66 20 69 74 73 20 63 6f 72 72 65 73 70 6f 6e  of its correspon
5230: 64 69 6e 67 20 70 72 69 6d 61 72 79 20 72 65 73  ding primary res
5240: 75 6c 74 20 63 6f 64 65 20 69 6e 0a 2a 2a 20 20  ult code in.**  
5250: 20 20 20 20 20 20 20 20 69 74 73 20 6c 65 61 73          its leas
5260: 74 20 73 69 67 6e 69 66 69 63 61 6e 74 20 38 20  t significant 8 
5270: 62 69 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  bits..*/.#define
5280: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45   SQLITE_IOERR_RE
5290: 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
52a0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
52b0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
52c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
52d0: 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28  RT_READ        (
52e0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
52f0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5300: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54  QLITE_IOERR_WRIT
5310: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  E             (S
5320: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33  QLITE_IOERR | (3
5330: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5340: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43  LITE_IOERR_FSYNC
5350: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5360: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c  LITE_IOERR | (4<
5370: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5380: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53  ITE_IOERR_DIR_FS
5390: 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c  YNC         (SQL
53a0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c  ITE_IOERR | (5<<
53b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
53c0: 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54  TE_IOERR_TRUNCAT
53d0: 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  E          (SQLI
53e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38  TE_IOERR | (6<<8
53f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5400: 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20  E_IOERR_FSTAT   
5410: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5420: 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29  E_IOERR | (7<<8)
5430: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5440: 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20  _IOERR_UNLOCK   
5450: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5460: 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29  _IOERR | (8<<8))
5470: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5480: 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20  IOERR_RDLOCK    
5490: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
54a0: 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a  IOERR | (9<<8)).
54b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
54c0: 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20  OERR_DELETE     
54d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
54e0: 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a  OERR | (10<<8)).
54f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5500: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20  OERR_BLOCKED    
5510: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5520: 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a  OERR | (11<<8)).
5530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5540: 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20  OERR_NOMEM      
5550: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5560: 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a  OERR | (12<<8)).
5570: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5580: 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20  OERR_ACCESS     
5590: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
55a0: 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a  OERR | (13<<8)).
55b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
55c0: 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56  OERR_CHECKRESERV
55d0: 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49  EDLOCK (SQLITE_I
55e0: 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a  OERR | (14<<8)).
55f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5600: 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20  OERR_LOCK       
5610: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5620: 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a  OERR | (15<<8)).
5630: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5640: 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20   Flags For File 
5650: 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20  Open Operations 
5660: 7b 48 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30  {H10230} <H11120
5670: 3e 20 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a  > <H12700>.**.**
5680: 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65   These bit value
5690: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
56a0: 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a  or use in the.**
56b0: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
56c0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  o the [sqlite3_o
56d0: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
56e0: 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68  ace and.** in th
56f0: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
5700: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
5710: 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  hod of the.** [s
5720: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
5730: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
5740: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
5750: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
5760: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
5770: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
5780: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
5790: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
57a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
57b0: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
57c0: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
57d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
57e0: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
57f0: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
5800: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
5810: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
5820: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
5830: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
5840: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
5850: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
5860: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
5870: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
5880: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
5890: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
58a0: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
58b0: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53  000400.#define S
58c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
58d0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
58e0: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
58f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
5900: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
5910: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
5920: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
5930: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
5940: 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53  002000.#define S
5950: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
5960: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
5970: 30 30 34 30 30 30 0a 23 64 65 66 69 6e 65 20 53  004000.#define S
5980: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
5990: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
59a0: 30 30 38 30 30 30 0a 23 64 65 66 69 6e 65 20 53  008000.#define S
59b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
59c0: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
59d0: 30 31 30 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  010000../*.** CA
59e0: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
59f0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 7b  haracteristics {
5a00: 48 31 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e  H10240} <H11120>
5a10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69  .**.** The xDevi
5a20: 63 65 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d  ceCapabilities m
5a30: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71  ethod of the [sq
5a40: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
5a50: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75  ].** object retu
5a60: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77  rns an integer w
5a70: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72  hich is a vector
5a80: 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a   of the these.**
5a90: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
5aa0: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
5ab0: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
5ac0: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
5ad0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
5ae0: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
5af0: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
5b00: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
5b10: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** T
5b20: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
5b30: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
5b40: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
5b50: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
5b60: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
5b70: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
5b80: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
5b90: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
5ba0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
5bb0: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
5bc0: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
5bd0: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
5be0: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
5bf0: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
5c00: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
5c10: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
5c20: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
5c30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
5c40: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
5c50: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
5c60: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
5c70: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
5c80: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
5c90: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
5ca0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
5cb0: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
5cc0: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
5cd0: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
5ce0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
5cf0: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
5d00: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
5d10: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
5d20: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
5d30: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
5d40: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
5d50: 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  te()..*/.#define
5d60: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5d70: 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 30 78  OMIC          0x
5d80: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65  00000001.#define
5d90: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5da0: 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 30 78  OMIC512       0x
5db0: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65  00000002.#define
5dc0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5dd0: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 30 78  OMIC1K        0x
5de0: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
5df0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5e00: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 30 78  OMIC2K        0x
5e10: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
5e20: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5e30: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 30 78  OMIC4K        0x
5e40: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65  00000010.#define
5e50: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5e60: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 30 78  OMIC8K        0x
5e70: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65  00000020.#define
5e80: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5e90: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 30 78  OMIC16K       0x
5ea0: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
5eb0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5ec0: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 30 78  OMIC32K       0x
5ed0: 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65  00000080.#define
5ee0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5ef0: 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 30 78  OMIC64K       0x
5f00: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65  00000100.#define
5f10: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
5f20: 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78  FE_APPEND     0x
5f30: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
5f40: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
5f50: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78  QUENTIAL      0x
5f60: 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20  00000400../*.** 
5f70: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
5f80: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48  ocking Levels {H
5f90: 31 30 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20  10250} <H11120> 
5fa0: 3c 48 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53  <H11310>.**.** S
5fb0: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
5fc0: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
5fd0: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
5fe0: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
5ff0: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
6000: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
6010: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
6020: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
6030: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6040: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
6050: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6060: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
6070: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
6080: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
6090: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
60a0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
60b0: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
60c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
60d0: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
60e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
60f0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
6100: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
6110: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
6120: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
6130: 20 7b 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32   {H10260} <H1112
6140: 30 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51  0>.**.** When SQ
6150: 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65  Lite invokes the
6160: 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20   xSync() method 
6170: 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  of an.** [sqlite
6180: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
6190: 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63  ject it uses a c
61a0: 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a  ombination of.**
61b0: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
61c0: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
61d0: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ond argument..**
61e0: 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c  .** When the SQL
61f0: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
6200: 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20  Y flag is used, 
6210: 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
6220: 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74  e.** sync operat
6230: 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  ion only needs t
6240: 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20  o flush data to 
6250: 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49  mass storage.  I
6260: 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  node.** informat
6270: 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  ion need not be 
6280: 66 6c 75 73 68 65 64 2e 20 54 68 65 20 53 51 4c  flushed. The SQL
6290: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
62a0: 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f  flag means.** to
62b0: 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   use normal fsyn
62c0: 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 20 54  c() semantics. T
62d0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  he SQLITE_SYNC_F
62e0: 55 4c 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a  ULL flag means.*
62f0: 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20  * to use Mac OS 
6300: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
6310: 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e   instead of fsyn
6320: 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  c()..*/.#define 
6330: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
6340: 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30  AL        0x0000
6350: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
6360: 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20  _SYNC_FULL      
6370: 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66      0x00003.#def
6380: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
6390: 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78  DATAONLY      0x
63a0: 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00010../*.** CAP
63b0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
63c0: 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61  ace Open File Ha
63d0: 6e 64 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c 53  ndle {H11110} <S
63e0: 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20  20110>.**.** An 
63f0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
6400: 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
6410: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e   an open file in
6420: 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72   the OS.** inter
6430: 66 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64  face layer.  Ind
6440: 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72  ividual OS inter
6450: 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  face implementat
6460: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
6470: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
6480: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
6490: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
64a0: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
64b0: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
64c0: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
64d0: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
64e0: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
64f0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
6500: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
6510: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
6520: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
6530: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
6540: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
6550: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
6560: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
6570: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
6580: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
6590: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
65a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
65b0: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
65c0: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
65d0: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
65e0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
65f0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
6600: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
6610: 64 73 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 32  ds Object {H1112
6620: 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a  0} <S20110>.**.*
6630: 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65  * Every file ope
6640: 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ned by the [sqli
6650: 74 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d  te3_vfs] xOpen m
6660: 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20  ethod populates 
6670: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  an.** [sqlite3_f
6680: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c  ile] object (or,
6690: 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20   more commonly, 
66a0: 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68  a subclass of th
66b0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
66c0: 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68  le] object) with
66d0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
66e0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
66f0: 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69  s object..** Thi
6700: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
6710: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65   the methods use
6720: 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  d to perform var
6730: 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a  ious operations.
6740: 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f  ** against the o
6750: 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65  pen file represe
6760: 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  nted by the [sql
6770: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
6780: 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  t..**.** The fla
6790: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
67a0: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20  Sync may be one 
67b0: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  of [SQLITE_SYNC_
67c0: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53  NORMAL] or.** [S
67d0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d  QLITE_SYNC_FULL]
67e0: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f  .  The first cho
67f0: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61  ice is the norma
6800: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68  l fsync()..** Th
6810: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20  e second choice 
6820: 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74  is a Mac OS X st
6830: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54  yle fullsync.  T
6840: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  he [SQLITE_SYNC_
6850: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61  DATAONLY].** fla
6860: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e  g may be ORed in
6870: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
6880: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20  t only the data 
6890: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61  of the file.** a
68a0: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65  nd not its inode
68b0: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e   needs to be syn
68c0: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ced..**.** The i
68d0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f  nteger values to
68e0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
68f0: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f  lock() are one o
6900: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  f.** <ul>.** <li
6910: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  > [SQLITE_LOCK_N
6920: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ONE],.** <li> [S
6930: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
6940: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
6950: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
6960: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
6970: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
6980: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
6990: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
69a0: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  SIVE]..** </ul>.
69b0: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65  ** xLock() incre
69c0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78  ases the lock. x
69d0: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73  Unlock() decreas
69e0: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20  es the lock..** 
69f0: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76  The xCheckReserv
6a00: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20  edLock() method 
6a10: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61  checks whether a
6a20: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ny database conn
6a30: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65  ection,.** eithe
6a40: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73  r in this proces
6a50: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68  s or in some oth
6a60: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68  er process, is h
6a70: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45  olding a RESERVE
6a80: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f  D,.** PENDING, o
6a90: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b  r EXCLUSIVE lock
6aa0: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49   on the file.  I
6ab0: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a  t returns true.*
6ac0: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b  * if such a lock
6ad0: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73   exists and fals
6ae0: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  e otherwise..**.
6af0: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74  ** The xFileCont
6b00: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20  rol() method is 
6b10: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66  a generic interf
6b20: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  ace that allows 
6b30: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d  custom.** VFS im
6b40: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f  plementations to
6b50: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f   directly contro
6b60: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75  l an open file u
6b70: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
6b80: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
6b90: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  l()] interface. 
6ba0: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22   The second "op"
6bb0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a   argument is an.
6bc0: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64  ** integer opcod
6bd0: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  e.  The third ar
6be0: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65  gument is a gene
6bf0: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65  ric pointer inte
6c00: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74  nded to.** point
6c10: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20   to a structure 
6c20: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e  that may contain
6c30: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70   arguments or sp
6c40: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a  ace in which to.
6c50: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20  ** write return 
6c60: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69  values.  Potenti
6c70: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c  al uses for xFil
6c80: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74  eControl() might
6c90: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   be.** functions
6ca0: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b   to enable block
6cb0: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74  ing locks with t
6cc0: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e  imeouts, to chan
6cd0: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e  ge the.** lockin
6ce0: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20  g strategy (for 
6cf0: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64  example to use d
6d00: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20  ot-file locks), 
6d10: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62  to inquire.** ab
6d20: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f  out the status o
6d30: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20  f a lock, or to 
6d40: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b  break stale lock
6d50: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a  s.  The SQLite.*
6d60: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20  * core reserves 
6d70: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73  all opcodes less
6d80: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74   than 100 for it
6d90: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20  s own use..** A 
6da0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
6db0: 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f  CKSTATE | list o
6dc0: 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20  f opcodes] less 
6dd0: 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69  than 100 is avai
6de0: 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  lable..** Applic
6df0: 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69  ations that defi
6e00: 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c  ne a custom xFil
6e10: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
6e20: 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64  should use opcod
6e30: 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68  es.** greater th
6e40: 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20  an 100 to avoid 
6e50: 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a  conflicts..**.**
6e60: 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65   The xSectorSize
6e70: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
6e80: 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a  s the sector siz
6e90: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69  e of the.** devi
6ea0: 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65  ce that underlie
6eb0: 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  s the file.  The
6ec0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20   sector size is 
6ed0: 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77  the.** minimum w
6ee0: 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65  rite that can be
6ef0: 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f   performed witho
6f00: 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a  ut disturbing.**
6f10: 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20   other bytes in 
6f20: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78  the file.  The x
6f30: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
6f40: 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f  stics().** metho
6f50: 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20  d returns a bit 
6f60: 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e  vector describin
6f70: 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74  g behaviors of t
6f80: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
6f90: 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c   device:.**.** <
6fa0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
6fb0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6fc0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6fd0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
6fe0: 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  2].** <li> [SQLI
6ff0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
7000: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
7010: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
7020: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
7030: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
7040: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
7050: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38  TE_IOCAP_ATOMIC8
7060: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
7070: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
7080: 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  6K].** <li> [SQL
7090: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
70a0: 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  32K].** <li> [SQ
70b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
70c0: 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C64K].** <li> [S
70d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
70e0: 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e  _APPEND].** <li>
70f0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
7100: 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f  EQUENTIAL].** </
7110: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  ul>.**.** The SQ
7120: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7130: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
7140: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
7150: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
7160: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
7170: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
7180: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
7190: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
71a0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
71b0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
71c0: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
71d0: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
71e0: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
71f0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
7200: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
7210: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
7220: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
7230: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
7240: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
7250: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
7260: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
7270: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
7280: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
7290: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
72a0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
72b0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
72c0: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
72d0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
72e0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
72f0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
7300: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
7310: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
7320: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
7330: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
7340: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
7350: 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28  .**.** If xRead(
7360: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
7370: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
7380: 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66  D it must also f
7390: 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e  ill.** in the un
73a0: 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66  read portions of
73b0: 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68   the buffer with
73c0: 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74   zeros.  A VFS t
73d0: 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20  hat.** fails to 
73e0: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
73f0: 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d  reads might seem
7400: 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76   to work.  Howev
7410: 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74  er,.** failure t
7420: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
7430: 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65  t reads will eve
7440: 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a  ntually lead to.
7450: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72  ** database corr
7460: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  uption..*/.typed
7470: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
7480: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c  3_io_methods sql
7490: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b  ite3_io_methods;
74a0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
74b0: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  io_methods {.  i
74c0: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
74d0: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
74e0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
74f0: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69  nt (*xRead)(sqli
7500: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a  te3_file*, void*
7510: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
7520: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
7530: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65  ;.  int (*xWrite
7540: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7550: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
7560: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
7570: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
7580: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29  int (*xTruncate)
7590: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
75a0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69  sqlite3_int64 si
75b0: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ze);.  int (*xSy
75c0: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  nc)(sqlite3_file
75d0: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  *, int flags);. 
75e0: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65   int (*xFileSize
75f0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7600: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
7610: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a  pSize);.  int (*
7620: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  xLock)(sqlite3_f
7630: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
7640: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c  t (*xUnlock)(sql
7650: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
7660: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b  ;.  int (*xCheck
7670: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71  ReservedLock)(sq
7680: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7690: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
76a0: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  t (*xFileControl
76b0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
76c0: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70   int op, void *p
76d0: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Arg);.  int (*xS
76e0: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74  ectorSize)(sqlit
76f0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7700: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63   (*xDeviceCharac
7710: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74  teristics)(sqlit
7720: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20  e3_file*);.  /* 
7730: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
7740: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
7750: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
7760: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
7770: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
7780: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
7790: 4f 70 63 6f 64 65 73 20 7b 48 31 31 33 31 30 7d  Opcodes {H11310}
77a0: 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S30800>.**.** 
77b0: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
77c0: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
77d0: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
77e0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
77f0: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
7800: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
7810: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68  bject and for th
7820: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
7830: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e  control()].** in
7840: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
7850: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
7860: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
7870: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
7880: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
7890: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
78a0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
78b0: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
78c0: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
78d0: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
78e0: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
78f0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
7900: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7910: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
7920: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
7930: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
7940: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
7950: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
7960: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
7970: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
7980: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
7990: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
79a0: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
79b0: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
79c0: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  g and only needs
79d0: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
79e0: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
79f0: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e  T.** is defined.
7a00: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
7a10: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
7a20: 54 45 20 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a  TE        1../*.
7a30: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
7a40: 65 78 20 48 61 6e 64 6c 65 20 7b 48 31 37 31 31  ex Handle {H1711
7a50: 30 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 0a 2a  0} <S20130>.**.*
7a60: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75  * The mutex modu
7a70: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  le within SQLite
7a80: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65   defines [sqlite
7a90: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61  3_mutex] to be a
7aa0: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79  n.** abstract ty
7ab0: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f  pe for a mutex o
7ac0: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
7ad0: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f  te core never lo
7ae0: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e  oks.** at the in
7af0: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
7b00: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c  ation of an [sql
7b10: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74  ite3_mutex].  It
7b20: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77   only.** deals w
7b30: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ith pointers to 
7b40: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
7b50: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  ex] object..**.*
7b60: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72  * Mutexes are cr
7b70: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
7b80: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
7b90: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
7ba0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
7bb0: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74  utex sqlite3_mut
7bc0: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ex;../*.** CAPI3
7bd0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
7be0: 65 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 34 30  e Object {H11140
7bf0: 7d 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20100>.**.**
7c00: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
7c10: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
7c20: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
7c30: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
7c40: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
7c50: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
7c60: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
7c70: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
7c80: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
7c90: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
7ca0: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
7cb0: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
7cc0: 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  stem"..**.** The
7cd0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
7ce0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
7cf0: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
7d00: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
7d10: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
7d20: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
7d30: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
7d40: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
7d50: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
7d60: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
7d70: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
7d80: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20  ncreased.  Note 
7d90: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
7da0: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
7db0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
7dc0: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
7dd0: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65  ransaction betwe
7de0: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  en.** SQLite ver
7df0: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33  sion 3.5.9 and 3
7e00: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65  .6.0 and yet the
7e10: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
7e20: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66  was not.** modif
7e30: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
7e40: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
7e50: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
7e60: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
7e70: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
7e80: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
7e90: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
7ea0: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
7eb0: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
7ec0: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
7ed0: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
7ee0: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
7ef0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
7f00: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
7f10: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
7f20: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
7f30: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
7f40: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
7f50: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
7f60: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
7f70: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
7f80: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
7f90: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
7fa0: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
7fb0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
7fc0: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
7fd0: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
7fe0: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
7ff0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
8000: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
8010: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
8020: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
8030: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
8040: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
8050: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
8060: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
8070: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
8080: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
8090: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
80a0: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
80b0: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
80c0: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
80d0: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
80e0: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
80f0: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
8100: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
8110: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
8120: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
8130: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
8140: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
8150: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
8160: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
8170: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
8180: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
8190: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
81a0: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
81b0: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
81c0: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
81d0: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
81e0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34  es..**.** {H1114
81f0: 31 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  1} SQLite will g
8200: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
8210: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
8220: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
8230: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
8240: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
8250: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
8260: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
8270: 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66  ame().  SQLite f
8280: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
8290: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
82a0: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
82b0: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
82c0: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
82d0: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 7b 45  is.** called. {E
82e0: 4e 44 7d 20 20 42 65 63 61 75 73 65 20 6f 66 20  ND}  Because of 
82f0: 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
8300: 74 65 6e 73 65 2c 0a 2a 2a 20 74 68 65 20 5b 73  tense,.** the [s
8310: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e  qlite3_file] can
8320: 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20   safely store a 
8330: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
8340: 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74  * filename if it
8350: 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62   needs to rememb
8360: 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  er the filename 
8370: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e  for some reason.
8380: 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65  .** If the zFile
8390: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
83a0: 73 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c  s xOpen is a NUL
83b0: 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78  L pointer then x
83c0: 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76  Open.** must inv
83d0: 69 74 65 20 69 74 73 20 6f 77 6e 20 74 65 6d 70  ite its own temp
83e0: 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74  orary name for t
83f0: 68 65 20 66 69 6c 65 2e 20 20 57 68 65 6e 65 76  he file.  Whenev
8400: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
8410: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
8420: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
8430: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
8440: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
8450: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
8460: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
8470: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
8480: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  OSE]..**.** {H11
8490: 31 34 32 7d 20 54 68 65 20 66 6c 61 67 73 20 61  142} The flags a
84a0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
84b0: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
84c0: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
84d0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
84e0: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
84f0: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
8500: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
8510: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
8520: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
8530: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
8540: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
8550: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
8560: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
8570: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
8580: 45 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49 66 20  E]. {END}.** If 
8590: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20  xOpen() opens a 
85a0: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74  file read-only t
85b0: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75  hen it sets *pOu
85c0: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63  tFlags to.** inc
85d0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
85e0: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74  N_READONLY].  Ot
85f0: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75  her bits in *pOu
8600: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65  tFlags may be se
8610: 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 33  t..**.** {H11143
8620: 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  } SQLite will al
8630: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
8640: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
8650: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
8660: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
8670: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
8680: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
8690: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
86a0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
86b0: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
86c0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
86d0: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
86e0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
86f0: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
8700: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
8710: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
8720: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
8730: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
8740: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
8750: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
8760: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
8770: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
8780: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
8790: 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  </ul> {END}.**.*
87a0: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69  * The file I/O i
87b0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61  mplementation ca
87c0: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74  n use the object
87d0: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a   type flags to.*
87e0: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79  * change the way
87f0: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66   it deals with f
8800: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  iles.  For examp
8810: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
8820: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  on.** that does 
8830: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63  not care about c
8840: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72  rash recovery or
8850: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   rollback might 
8860: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e  make.** the open
8870: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69   of a journal fi
8880: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69  le a no-op.  Wri
8890: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72  tes to this jour
88a0: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73  nal would.** als
88b0: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64  o be no-ops, and
88c0: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   any attempt to 
88d0: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
88e0: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a   would return.**
88f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20   SQLITE_IOERR.  
8900: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  Or the implement
8910: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f  ation might reco
8920: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74  gnize that a dat
8930: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69  abase.** file wi
8940: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65  ll be doing page
8950: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20  -aligned sector 
8960: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73  reads and writes
8970: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20   in a random.** 
8980: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70  order and set up
8990: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
89a0: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
89b0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67  **.** SQLite mig
89c0: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ht also add one 
89d0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
89e0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
89f0: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  pen method:.**.*
8a00: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
8a10: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
8a20: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c  TEONCLOSE].** <l
8a30: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
8a40: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f  EXCLUSIVE].** </
8a50: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34  ul>.**.** {H1114
8a60: 35 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  5} The [SQLITE_O
8a70: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
8a80: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
8a90: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
8aa0: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
8ab0: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
8ac0: 7b 48 31 31 31 34 36 7d 20 54 68 65 20 5b 53 51  {H11146} The [SQ
8ad0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
8ae0: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c  ONCLOSE].** will
8af0: 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50   be set for TEMP
8b00: 20 20 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75    databases, jou
8b10: 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75  rnals and for su
8b20: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a  bjournals..**.**
8b30: 20 7b 48 31 31 31 34 37 7d 20 54 68 65 20 5b 53   {H11147} The [S
8b40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
8b50: 53 49 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  SIVE] flag means
8b60: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
8b70: 20 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f   be opened.** fo
8b80: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
8b90: 73 73 2e 20 20 54 68 69 73 20 66 6c 61 67 20 69  ss.  This flag i
8ba0: 73 20 73 65 74 20 66 6f 72 20 61 6c 6c 20 66 69  s set for all fi
8bb0: 6c 65 73 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f  les except.** fo
8bc0: 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62  r the main datab
8bd0: 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20  ase file..**.** 
8be0: 7b 48 31 31 31 34 38 7d 20 41 74 20 6c 65 61 73  {H11148} At leas
8bf0: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73  t szOsFile bytes
8c00: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61   of memory are a
8c10: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
8c20: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68  te.** to hold th
8c30: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  e  [sqlite3_file
8c40: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73  ] structure pass
8c50: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a  ed as the third.
8c60: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  ** argument to x
8c70: 4f 70 65 6e 2e 20 7b 45 4e 44 7d 20 20 54 68 65  Open. {END}  The
8c80: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f   xOpen method do
8c90: 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a  es not have to.*
8ca0: 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73  * allocate the s
8cb0: 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f  tructure; it sho
8cc0: 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74  uld just fill it
8cd0: 20 69 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31   in..**.** {H111
8ce0: 34 39 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72  49} The flags ar
8cf0: 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73  gument to xAcces
8d00: 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49  s() may be [SQLI
8d10: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
8d20: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72  ].** to test for
8d30: 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f   the existence o
8d40: 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51  f a file, or [SQ
8d50: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
8d60: 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73  WRITE] to.** tes
8d70: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
8d80: 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64   is readable and
8d90: 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53   writable, or [S
8da0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
8db0: 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68  D].** to test wh
8dc0: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
8dd0: 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c  at least readabl
8de0: 65 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 66 69  e. {END}  The fi
8df0: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
8e00: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
8e10: 7b 48 31 31 31 35 30 7d 20 53 51 4c 69 74 65 20  {H11150} SQLite 
8e20: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
8e30: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
8e40: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
8e50: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
8e60: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
8e70: 61 74 68 6e 61 6d 65 2e 20 7b 48 31 31 31 35 31  athname. {H11151
8e80: 7d 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65  } The exact size
8e90: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
8ea0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
8eb0: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
8ec0: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
8ed0: 6d 65 74 68 6f 64 73 2e 20 7b 45 4e 44 7d 20 20  methods. {END}  
8ee0: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
8ef0: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
8f00: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
8f10: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
8f20: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
8f30: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
8f40: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
8f50: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
8f60: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
8f70: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
8f80: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
8f90: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
8fa0: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
8fb0: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
8fc0: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
8fd0: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
8fe0: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
8ff0: 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72  eep(), and xCurr
9000: 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66  entTime() interf
9010: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
9020: 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20  strictly a part 
9030: 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65  of the filesyste
9040: 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a  m, but they are.
9050: 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ** included in t
9060: 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65  he VFS structure
9070: 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73   for completenes
9080: 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  s..** The xRando
9090: 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e  mness() function
90a0: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74   attempts to ret
90b0: 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73  urn nBytes bytes
90c0: 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c  .** of good-qual
90d0: 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69  ity randomness i
90e0: 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72  nto zOut.  The r
90f0: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a  eturn value is.*
9100: 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d  * the actual num
9110: 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
9120: 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
9130: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65  ned..** The xSle
9140: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73  ep() method caus
9150: 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  es the calling t
9160: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66  hread to sleep f
9170: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74  or at.** least t
9180: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63  he number of mic
9190: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e  roseconds given.
91a0: 20 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 69    The xCurrentTi
91b0: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  me().** method r
91c0: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20  eturns a Julian 
91d0: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74  Day Number for t
91e0: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20  he current date 
91f0: 61 6e 64 20 74 69 6d 65 2e 0a 2a 2f 0a 74 79 70  and time..*/.typ
9200: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
9210: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
9220: 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  vfs;.struct sqli
9230: 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20  te3_vfs {.  int 
9240: 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20  iVersion;       
9250: 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72       /* Structur
9260: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
9270: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
9280: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
9290: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
92a0: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
92b0: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
92c0: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
92d0: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
92e0: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
92f0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
9300: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
9310: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
9320: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
9330: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
9340: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
9350: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
9360: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
9370: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
9380: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
9390: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
93a0: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
93b0: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
93c0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
93d0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
93e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
93f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
9400: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
9410: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
9420: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
9430: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
9440: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
9450: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
9460: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
9470: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
9480: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
9490: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
94a0: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
94b0: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
94c0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
94d0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
94e0: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
94f0: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
9500: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
9510: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
9520: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
9530: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
9540: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
9550: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
9560: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
9570: 20 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69   *(*xDlSym)(sqli
9580: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20  te3_vfs*,void*, 
9590: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d  const char *zSym
95a0: 62 6f 6c 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  bol);.  void (*x
95b0: 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  DlClose)(sqlite3
95c0: 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20  _vfs*, void*);. 
95d0: 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65   int (*xRandomne
95e0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
95f0: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
9600: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
9610: 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65  (*xSleep)(sqlite
9620: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72  3_vfs*, int micr
9630: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
9640: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
9650: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64  (sqlite3_vfs*, d
9660: 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  ouble*);.  int (
9670: 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28  *xGetLastError)(
9680: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
9690: 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a  t, char *);.  /*
96a0: 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20   New fields may 
96b0: 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66  be appended in f
96c0: 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20  igure versions. 
96d0: 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20   The iVersion.  
96e0: 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e  ** value will in
96f0: 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72  crement whenever
9700: 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 2a   this happens. *
9710: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
9720: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
9730: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20  the xAccess VFS 
9740: 6d 65 74 68 6f 64 20 7b 48 31 31 31 39 30 7d 20  method {H11190} 
9750: 3c 48 31 31 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 7b  <H11140>.**.** {
9760: 48 31 31 31 39 31 7d 20 54 68 65 73 65 20 69 6e  H11191} These in
9770: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
9780: 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74  can be used as t
9790: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
97a0: 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63  er to.** the xAc
97b0: 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61  cess method of a
97c0: 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  n [sqlite3_vfs] 
97d0: 6f 62 6a 65 63 74 2e 20 7b 45 4e 44 7d 20 20 54  object. {END}  T
97e0: 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a  hey determine.**
97f0: 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65   what kind of pe
9800: 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41  rmissions the xA
9810: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20  ccess method is 
9820: 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20  looking for..** 
9830: 7b 48 31 31 31 39 32 7d 20 57 69 74 68 20 53 51  {H11192} With SQ
9840: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
9850: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
9860: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
9870: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
9880: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
9890: 0a 2a 2a 20 7b 48 31 31 31 39 33 7d 20 57 69 74  .** {H11193} Wit
98a0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
98b0: 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78  READWRITE, the x
98c0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
98d0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
98e0: 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74 68  the file is both
98f0: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
9900: 69 74 61 62 6c 65 2e 0a 2a 2a 20 7b 48 31 31 31  itable..** {H111
9910: 39 34 7d 20 57 69 74 68 20 53 51 4c 49 54 45 5f  94} With SQLITE_
9920: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
9930: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
9940: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
9950: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
9960: 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69  adable..*/.#defi
9970: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
9980: 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65  _EXISTS    0.#de
9990: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
99a0: 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23  SS_READWRITE 1.#
99b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
99c0: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
99d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
99e0: 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65  : Initialize The
99f0: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20   SQLite Library 
9a00: 7b 48 31 30 31 33 30 7d 20 3c 53 32 30 30 30 30  {H10130} <S20000
9a10: 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20  ><S30100>.**.** 
9a20: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
9a30: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
9a40: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
9a50: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
9a60: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
9a70: 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74  _shutdown() rout
9a80: 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74  ine.** deallocat
9a90: 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  es any resources
9aa0: 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63   that were alloc
9ab0: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
9ac0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a  initialize()..**
9ad0: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
9ae0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9af0: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
9b00: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
9b10: 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  is.** the first 
9b20: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
9b30: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
9b40: 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20  oked during the 
9b50: 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74  lifetime of.** t
9b60: 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  he process, or i
9b70: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
9b80: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
9b90: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
9ba0: 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nvoked.** follow
9bb0: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71  ing a call to sq
9bc0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
9bd0: 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63  .  Only an effec
9be0: 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20  tive call.** of 
9bf0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9c00: 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e  ze() does any in
9c10: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41  itialization.  A
9c20: 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a  ll other calls.*
9c30: 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  * are harmless n
9c40: 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f  o-ops..**.** Amo
9c50: 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c  ng other things,
9c60: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9c70: 69 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f  ize() shall invo
9c80: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  ke.** sqlite3_os
9c90: 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61  _init().  Simila
9ca0: 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 68 75  rly, sqlite3_shu
9cb0: 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c  tdown().** shall
9cc0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
9cd0: 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20  os_end()..**.** 
9ce0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
9cf0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
9d00: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
9d10: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e  _OK] on success.
9d20: 0a 2a 2a 20 49 66 20 66 6f 72 20 73 6f 6d 65 20  .** If for some 
9d30: 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  reason, sqlite3_
9d40: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
9d50: 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61  unable to initia
9d60: 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72  lize.** the libr
9d70: 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20  ary (perhaps it 
9d80: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
9d90: 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72  ocate a needed r
9da0: 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20  esource such.** 
9db0: 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72  as a mutex) it r
9dc0: 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72  eturns an [error
9dd0: 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61   code] other tha
9de0: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  n [SQLITE_OK]..*
9df0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
9e00: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
9e10: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
9e20: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
9e30: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
9e40: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
9e50: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
9e60: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
9e70: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
9e80: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
9e90: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
9ea0: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
9eb0: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
9ec0: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
9ed0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9ee0: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
9ef0: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
9f00: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
9f10: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
9f20: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
9f30: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
9f40: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
9f50: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
9f60: 6c 72 65 61 64 79 2e 20 20 48 6f 77 65 76 65 72  lready.  However
9f70: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
9f80: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
9f90: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
9fa0: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
9fb0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
9fc0: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
9fd0: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
9fe0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9ff0: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
a000: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
a010: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
a020: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
a030: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
a040: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
a050: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
a060: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
a070: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
a080: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
a090: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
a0a0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
a0b0: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
a0c0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
a0d0: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
a0e0: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
a0f0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
a100: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
a110: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
a120: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
a130: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
a140: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
a150: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
a160: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
a170: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
a180: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
a190: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
a1a0: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
a1b0: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
a1c0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
a1d0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
a1e0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
a1f0: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
a200: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
a210: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
a220: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
a230: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
a240: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
a250: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
a260: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
a270: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
a280: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
a290: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
a2a0: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
a2b0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
a2c0: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
a2d0: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
a2e0: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
a2f0: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
a300: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
a310: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
a320: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
a330: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
a340: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
a350: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
a360: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
a370: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
a380: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
a390: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
a3a0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
a3b0: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
a3c0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
a3d0: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
a3e0: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
a3f0: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
a400: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
a410: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
a420: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
a430: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
a440: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
a450: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
a460: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
a470: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
a480: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
a490: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
a4a0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
a4b0: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
a4c0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a4d0: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
a4e0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
a4f0: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
a500: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
a510: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
a520: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
a530: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
a540: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 75  s compiled for u
a550: 6e 69 78 2c 20 77 69 6e 64 6f 77 73 2c 20 6f 72  nix, windows, or
a560: 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 62   os/2..** When b
a570: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
a580: 6c 61 74 66 6f 72 6d 73 20 28 75 73 69 6e 67 20  latforms (using 
a590: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
a5a0: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
a5b0: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
a5c0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
a5d0: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
a5e0: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
a5f0: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
a600: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
a610: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
a620: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
a630: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
a640: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
a650: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
a660: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
a670: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
a680: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
a690: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
a6a0: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
a6b0: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
a6c0: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
a6d0: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
a6e0: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
a6f0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
a700: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
a710: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
a720: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
a730: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
a740: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
a750: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
a760: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48  QLite Library {H
a770: 31 34 31 30 30 7d 20 3c 53 32 30 30 30 30 3e 3c  14100} <S20000><
a780: 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S30200>.** EXPER
a790: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
a7a0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
a7b0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
a7c0: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
a7d0: 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
a7e0: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
a7f0: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
a800: 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
a810: 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
a820: 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
a830: 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
a840: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
a850: 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
a860: 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
a870: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
a880: 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
a890: 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
a8a0: 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
a8b0: 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
a8c0: 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
a8d0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
a8e0: 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
a8f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
a900: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
a910: 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
a920: 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70  eadsafe.  The ap
a930: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
a940: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t insure that no
a950: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
a960: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
a970: 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
a980: 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
a990: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
a9a0: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72  is running.  Fur
a9b0: 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65  thermore, sqlite
a9c0: 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61  3_config().** ma
a9d0: 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
a9e0: 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
a9f0: 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
aa00: 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
aa10: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
aa20: 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
aa30: 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
aa40: 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
aa50: 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
aa60: 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  hat sqlite3_conf
aa70: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
aa80: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
aa90: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
aaa0: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
aab0: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
aac0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
aad0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
aae0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
aaf0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
ab00: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
ab10: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
ab20: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63  SINGLETHREAD | c
ab30: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
ab40: 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
ab50: 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
ab60: 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
ab70: 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
ab80: 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
ab90: 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
aba0: 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
abb0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
abc0: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
abd0: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
abe0: 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
abf0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
ac00: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63  ..**.** When a c
ac10: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
ac20: 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69  ion is set, sqli
ac30: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  te3_config() ret
ac40: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
ac50: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 74 69  ..** If the opti
ac60: 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72  on is unknown or
ac70: 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
ac80: 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74  e to set the opt
ac90: 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ion.** then this
aca0: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
acb0: 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72   a non-zero [err
acc0: 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
acd0: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
ace0: 2a 20 7b 48 31 34 31 30 33 7d 20 41 20 73 75 63  * {H14103} A suc
acf0: 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
ad00: 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63  on of [sqlite3_c
ad10: 6f 6e 66 69 67 28 29 5d 20 73 68 61 6c 6c 20 72  onfig()] shall r
ad20: 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
ad30: 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a    [SQLITE_OK]..*
ad40: 2a 0a 2a 2a 20 7b 48 31 34 31 30 36 7d 20 54 68  *.** {H14106} Th
ad50: 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
ad60: 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73  g()] interface s
ad70: 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  hall return [SQL
ad80: 49 54 45 5f 4d 49 53 55 53 45 5d 0a 2a 2a 20 20  ITE_MISUSE].**  
ad90: 20 20 20 20 20 20 20 20 69 66 20 69 74 20 69 73          if it is
ada0: 20 69 6e 76 6f 6b 65 64 20 69 6e 20 62 65 74 77   invoked in betw
adb0: 65 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  een calls to [sq
adc0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
add0: 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ()] and.**      
ade0: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 68 75      [sqlite3_shu
adf0: 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  tdown()]..**.** 
ae00: 7b 48 31 34 31 32 30 7d 20 41 20 73 75 63 63 65  {H14120} A succe
ae10: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
ae20: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
ae30: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
ae40: 4e 47 4c 45 54 48 52 45 41 44 5d 29 0a 2a 2a 20  NGLETHREAD]).** 
ae50: 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 73           shall s
ae60: 65 74 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  et the default [
ae70: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
ae80: 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  to Single-thread
ae90: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 32 33 7d  ..**.** {H14123}
aea0: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
aeb0: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
aec0: 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
aed0: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
aee0: 44 5d 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  D]).**          
aef0: 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 64 65  shall set the de
af00: 66 61 75 6c 74 20 5b 74 68 72 65 61 64 69 6e 67  fault [threading
af10: 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
af20: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  thread..**.** {H
af30: 31 34 31 32 36 7d 20 41 20 73 75 63 63 65 73 73  14126} A success
af40: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
af50: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
af60: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
af70: 41 4c 49 5a 45 44 5d 29 0a 2a 2a 20 20 20 20 20  ALIZED]).**     
af80: 20 20 20 20 20 73 68 61 6c 6c 20 73 65 74 20 74       shall set t
af90: 68 65 20 64 65 66 61 75 6c 74 20 5b 74 68 72 65  he default [thre
afa0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
afb0: 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  erialized..**.**
afc0: 20 7b 48 31 34 31 32 39 7d 20 41 20 73 75 63 63   {H14129} A succ
afd0: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
afe0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
aff0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
b000: 55 54 45 58 5d 2c 58 29 0a 2a 2a 20 20 20 20 20  UTEX],X).**     
b010: 20 20 20 20 20 77 68 65 72 65 20 58 20 69 73 20       where X is 
b020: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
b030: 69 6e 69 74 69 61 6c 69 7a 65 64 20 5b 73 71 6c  initialized [sql
b040: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
b050: 64 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ds].**          
b060: 6f 62 6a 65 63 74 20 73 68 61 6c 6c 20 63 61 75  object shall cau
b070: 73 65 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  se all subsequen
b080: 74 20 6d 75 74 65 78 20 6f 70 65 72 61 74 69 6f  t mutex operatio
b090: 6e 73 20 70 65 72 66 6f 72 6d 65 64 0a 2a 2a 20  ns performed.** 
b0a0: 20 20 20 20 20 20 20 20 20 62 79 20 53 51 4c 69           by SQLi
b0b0: 74 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d 75  te to use the mu
b0c0: 74 65 78 20 6d 65 74 68 6f 64 73 20 74 68 61 74  tex methods that
b0d0: 20 77 65 72 65 20 70 72 65 73 65 6e 74 20 69 6e   were present in
b0e0: 20 58 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64   X.**          d
b0f0: 75 72 69 6e 67 20 74 68 65 20 63 61 6c 6c 20 74  uring the call t
b100: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
b110: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34  g()]..**.** {H14
b120: 31 33 32 7d 20 41 20 73 75 63 63 65 73 73 66 75  132} A successfu
b130: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
b140: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
b150: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
b160: 45 58 5d 2c 58 29 0a 2a 2a 20 20 20 20 20 20 20  EX],X).**       
b170: 20 20 20 77 68 65 72 65 20 58 20 69 73 20 61 20     where X is a 
b180: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73  pointer to an [s
b190: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
b1a0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 0a 2a 2a  hods] object .**
b1b0: 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20            shall 
b1c0: 6f 76 65 72 77 72 69 74 65 20 74 68 65 20 63 6f  overwrite the co
b1d0: 6e 74 65 6e 74 20 6f 66 20 5b 73 71 6c 69 74 65  ntent of [sqlite
b1e0: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
b1f0: 20 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20 20   object.**      
b200: 20 20 20 20 77 69 74 68 20 74 68 65 20 6d 75 74      with the mut
b210: 65 78 20 6d 65 74 68 6f 64 73 20 63 75 72 72 65  ex methods curre
b220: 6e 74 6c 79 20 69 6e 20 75 73 65 20 62 79 20 53  ntly in use by S
b230: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  QLite..**.** {H1
b240: 34 31 33 35 7d 20 41 20 73 75 63 63 65 73 73 66  4135} A successf
b250: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
b260: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
b270: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
b280: 43 5d 2c 4d 29 0a 2a 2a 20 20 20 20 20 20 20 20  C],M).**        
b290: 20 20 77 68 65 72 65 20 4d 20 69 73 20 61 20 70    where M is a p
b2a0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 69  ointer to an ini
b2b0: 74 69 61 6c 69 7a 65 64 20 5b 73 71 6c 69 74 65  tialized [sqlite
b2c0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
b2d0: 2a 20 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63  *          objec
b2e0: 74 20 73 68 61 6c 6c 20 63 61 75 73 65 20 61 6c  t shall cause al
b2f0: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 6d 65 6d  l subsequent mem
b300: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ory allocation o
b310: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 20 20 20  perations.**    
b320: 20 20 20 20 20 20 70 65 72 66 6f 72 6d 65 64 20        performed 
b330: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  by SQLite to use
b340: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 74 68 61   the methods tha
b350: 74 20 77 65 72 65 20 70 72 65 73 65 6e 74 20 69  t were present i
b360: 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4d  n .**          M
b370: 20 64 75 72 69 6e 67 20 74 68 65 20 63 61 6c 6c   during the call
b380: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
b390: 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  fig()]..**.** {H
b3a0: 31 34 31 33 38 7d 20 41 20 73 75 63 63 65 73 73  14138} A success
b3b0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
b3c0: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
b3d0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
b3e0: 41 4c 4c 4f 43 5d 2c 4d 29 0a 2a 2a 20 20 20 20  ALLOC],M).**    
b3f0: 20 20 20 20 20 20 77 68 65 72 65 20 4d 20 69 73        where M is
b400: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
b410: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
b420: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 73 68  thods] object sh
b430: 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
b440: 6f 76 65 72 77 72 69 74 65 20 74 68 65 20 63 6f  overwrite the co
b450: 6e 74 65 6e 74 20 6f 66 20 5b 73 71 6c 69 74 65  ntent of [sqlite
b460: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 6f  3_mem_methods] o
b470: 62 6a 65 63 74 20 77 69 74 68 20 0a 2a 2a 20 20  bject with .**  
b480: 20 20 20 20 20 20 20 20 74 68 65 20 6d 65 6d 6f          the memo
b490: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6d 65  ry allocation me
b4a0: 74 68 6f 64 73 20 63 75 72 72 65 6e 74 6c 79 20  thods currently 
b4b0: 69 6e 20 75 73 65 20 62 79 0a 2a 2a 20 20 20 20  in use by.**    
b4c0: 20 20 20 20 20 20 53 51 4c 69 74 65 2e 0a 2a 2a        SQLite..**
b4d0: 0a 2a 2a 20 7b 48 31 34 31 34 31 7d 20 41 20 73  .** {H14141} A s
b4e0: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
b4f0: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
b500: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
b510: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 31 29 0a  G_MEMSTATUS],1).
b520: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c  **          shal
b530: 6c 20 65 6e 61 62 6c 65 20 74 68 65 20 6d 65 6d  l enable the mem
b540: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
b550: 74 61 74 75 73 20 63 6f 6c 6c 65 63 74 69 6f 6e  tatus collection
b560: 20 6c 6f 67 69 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48   logic..**.** {H
b570: 31 34 31 34 34 7d 20 41 20 73 75 63 63 65 73 73  14144} A success
b580: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
b590: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
b5a0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
b5b0: 54 41 54 55 53 5d 2c 30 29 0a 2a 2a 20 20 20 20  TATUS],0).**    
b5c0: 20 20 20 20 20 20 73 68 61 6c 6c 20 64 69 73 61        shall disa
b5d0: 62 6c 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ble the memory a
b5e0: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 75 73  llocation status
b5f0: 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6c 6f 67 69   collection logi
b600: 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 34 37  c..**.** {H14147
b610: 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  } The memory all
b620: 6f 63 61 74 69 6f 6e 20 73 74 61 74 75 73 20 63  ocation status c
b630: 6f 6c 6c 65 63 74 69 6f 6e 20 6c 6f 67 69 63 20  ollection logic 
b640: 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20  shall be.**     
b650: 20 20 20 20 20 65 6e 61 62 6c 65 64 20 62 79 20       enabled by 
b660: 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b  default..**.** {
b670: 48 31 34 31 35 30 7d 20 41 20 73 75 63 63 65 73  H14150} A succes
b680: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
b690: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
b6a0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
b6b0: 41 54 43 48 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20  ATCH],S,Z,N).** 
b6c0: 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20 5a           where Z
b6d0: 20 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d 6e   and N are non-n
b6e0: 65 67 61 74 69 76 65 20 69 6e 74 65 67 65 72 73  egative integers
b6f0: 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 20   and .**        
b700: 20 20 53 20 69 73 20 61 20 70 6f 69 6e 74 65 72    S is a pointer
b710: 20 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 6d   to an aligned m
b720: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 6e 6f 74  emory buffer not
b730: 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20   less than.**   
b740: 20 20 20 20 20 20 20 5a 2a 4e 20 62 79 74 65 73         Z*N bytes
b750: 20 69 6e 20 73 69 7a 65 20 73 68 61 6c 6c 20 63   in size shall c
b760: 61 75 73 65 20 53 20 74 6f 20 62 65 20 75 73 65  ause S to be use
b770: 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
b780: 20 20 20 20 20 5b 73 63 72 61 74 63 68 20 6d 65       [scratch me
b790: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
b7a0: 66 6f 72 20 61 73 20 6d 61 6e 79 20 61 73 20 4e  for as many as N
b7b0: 20 73 69 6d 75 6c 61 74 61 6e 65 6f 75 73 0a 2a   simulataneous.*
b7c0: 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63  *          alloc
b7d0: 61 74 69 6f 6e 73 20 65 61 63 68 20 6f 66 20 73  ations each of s
b7e0: 69 7a 65 20 5a 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ize Z..**.** {H1
b7f0: 34 31 35 33 7d 20 41 20 73 75 63 63 65 73 73 66  4153} A successf
b800: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
b810: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
b820: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
b830: 43 48 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 20 20  CH],S,Z,N).**   
b840: 20 20 20 20 20 20 20 77 68 65 72 65 20 53 20 69         where S i
b850: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
b860: 20 73 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 74   shall disable t
b870: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
b880: 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61  scratch memory a
b890: 6c 6c 6f 63 61 74 6f 72 5d 2e 0a 2a 2a 0a 2a 2a  llocator]..**.**
b8a0: 20 7b 48 31 34 31 35 36 7d 20 41 20 73 75 63 63   {H14156} A succ
b8b0: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 0a 2a  essful call to.*
b8c0: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
b8d0: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
b8e0: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
b8f0: 41 43 48 45 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20  ACHE],S,Z,N).** 
b900: 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20 5a           where Z
b910: 20 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d 6e   and N are non-n
b920: 65 67 61 74 69 76 65 20 69 6e 74 65 67 65 72 73  egative integers
b930: 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 20   and .**        
b940: 20 20 53 20 69 73 20 61 20 70 6f 69 6e 74 65 72    S is a pointer
b950: 20 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 6d   to an aligned m
b960: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 6e 6f 74  emory buffer not
b970: 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20   less than.**   
b980: 20 20 20 20 20 20 20 5a 2a 4e 20 62 79 74 65 73         Z*N bytes
b990: 20 69 6e 20 73 69 7a 65 20 73 68 61 6c 6c 20 63   in size shall c
b9a0: 61 75 73 65 20 53 20 74 6f 20 62 65 20 75 73 65  ause S to be use
b9b0: 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
b9c0: 20 20 20 20 20 5b 70 61 67 65 63 61 63 68 65 20       [pagecache 
b9d0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
b9e0: 5d 20 66 6f 72 20 61 73 20 6d 61 6e 79 20 61 73  ] for as many as
b9f0: 20 4e 20 73 69 6d 75 6c 61 74 61 6e 65 6f 75 73   N simulataneous
ba00: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c  .**          all
ba10: 6f 63 61 74 69 6f 6e 73 20 65 61 63 68 20 6f 66  ocations each of
ba20: 20 73 69 7a 65 20 5a 2e 0a 2a 2a 0a 2a 2a 20 7b   size Z..**.** {
ba30: 48 31 34 31 35 39 7d 20 41 20 73 75 63 63 65 73  H14159} A succes
ba40: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  sful call to.** 
ba50: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
ba60: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
ba70: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
ba80: 48 45 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 20 20  HE],S,Z,N).**   
ba90: 20 20 20 20 20 20 20 77 68 65 72 65 20 53 20 69         where S i
baa0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
bab0: 20 73 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 74   shall disable t
bac0: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
bad0: 70 61 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79  pagecache memory
bae0: 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 0a 2a 2a 0a   allocator]..**.
baf0: 2a 2a 20 7b 48 31 34 31 36 32 7d 20 41 20 73 75  ** {H14162} A su
bb00: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
bb10: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
bb20: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
bb30: 5f 48 45 41 50 5d 2c 48 2c 5a 2c 4e 29 0a 2a 2a  _HEAP],H,Z,N).**
bb40: 20 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20            where 
bb50: 5a 20 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d  Z and N are non-
bb60: 6e 65 67 61 74 69 76 65 20 69 6e 74 65 67 65 72  negative integer
bb70: 73 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20  s and .**       
bb80: 20 20 20 48 20 69 73 20 61 20 70 6f 69 6e 74 65     H is a pointe
bb90: 72 20 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20  r to an aligned 
bba0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 6e 6f  memory buffer no
bbb0: 74 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20  t less than.**  
bbc0: 20 20 20 20 20 20 20 20 5a 20 62 79 74 65 73 20          Z bytes 
bbd0: 69 6e 20 73 69 7a 65 20 73 68 61 6c 6c 20 65 6e  in size shall en
bbe0: 61 62 6c 65 20 74 68 65 20 5b 6d 65 6d 73 79 73  able the [memsys
bbf0: 35 5d 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  5] memory alloca
bc00: 74 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tor.**          
bc10: 61 6e 64 20 63 61 75 73 65 20 69 74 20 74 6f 20  and cause it to 
bc20: 75 73 65 20 62 75 66 66 65 72 20 53 20 61 73 20  use buffer S as 
bc30: 69 74 73 20 6d 65 6d 6f 72 79 20 73 6f 75 72 63  its memory sourc
bc40: 65 20 61 6e 64 20 74 6f 20 75 73 65 0a 2a 2a 20  e and to use.** 
bc50: 20 20 20 20 20 20 20 20 20 61 20 6d 69 6e 69 6d           a minim
bc60: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
bc70: 7a 65 20 6f 66 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b  ze of N..**.** {
bc80: 48 31 34 31 36 35 7d 20 41 20 73 75 63 63 65 73  H14165} A succes
bc90: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
bca0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
bcb0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
bcc0: 50 5d 2c 48 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20  P],H,Z,N).**    
bcd0: 20 20 20 20 20 20 77 68 65 72 65 20 48 20 69 73        where H is
bce0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
bcf0: 73 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 68  shall disable th
bd00: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 6d  e.**          [m
bd10: 65 6d 73 79 73 35 5d 20 6d 65 6d 6f 72 79 20 61  emsys5] memory a
bd20: 6c 6c 6f 63 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  llocator..**.** 
bd30: 7b 48 31 34 31 36 38 7d 20 41 20 73 75 63 63 65  {H14168} A succe
bd40: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
bd50: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
bd60: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
bd70: 4f 4b 41 53 49 44 45 5d 2c 5a 2c 4e 29 0a 2a 2a  OKASIDE],Z,N).**
bd80: 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20            shall 
bd90: 63 61 75 73 65 20 74 68 65 20 64 65 66 61 75 6c  cause the defaul
bda0: 74 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  t [lookaside mem
bdb0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63  ory allocator] c
bdc0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
bdd0: 20 20 20 20 20 20 20 20 20 66 6f 72 20 6e 65 77           for new
bde0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
bdf0: 63 74 69 6f 6e 73 5d 20 74 6f 20 62 65 20 4e 20  ctions] to be N 
be00: 73 6c 6f 74 73 20 6f 66 20 5a 20 62 79 74 65 73  slots of Z bytes
be10: 20 65 61 63 68 2e 0a 2a 2f 0a 53 51 4c 49 54 45   each..*/.SQLITE
be20: 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e  _EXPERIMENTAL in
be30: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  t sqlite3_config
be40: 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  (int, ...);../*.
be50: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
be60: 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20  figure database 
be70: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 20 7b 48 31  connections  {H1
be80: 34 32 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  4200} <S20000>.*
be90: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
bea0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
beb0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
bec0: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
bed0: 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61  o make configura
bee0: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
bef0: 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  to a [database c
bf00: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
bf10: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69   interface is si
bf20: 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  milar to.** [sql
bf30: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65  ite3_config()] e
bf40: 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63  xcept that the c
bf50: 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20  hanges apply to 
bf60: 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74  a single.** [dat
bf70: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
bf80: 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20  ] (specified in 
bf90: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
bfa0: 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  nt).  The.** sql
bfb0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
bfc0: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 6f   interface can o
bfd0: 6e 6c 79 20 62 65 20 75 73 65 64 20 69 6d 6d 65  nly be used imme
bfe0: 64 69 61 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a  diately after.**
bff0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
c000: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 72 65 61  nnection is crea
c010: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
c020: 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b  e3_open()],.** [
c030: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
c040: 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ], or [sqlite3_o
c050: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a  pen_v2()].  .**.
c060: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
c070: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
c080: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c  3_db_config(D,V,
c090: 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20  ...)  is the.** 
c0a0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
c0b0: 72 62 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20  rb - an integer 
c0c0: 63 6f 64 65 20 74 68 61 74 20 69 6e 64 69 63 61  code that indica
c0d0: 74 65 73 20 77 68 61 74 0a 2a 2a 20 61 73 70 65  tes what.** aspe
c0e0: 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  ct of the [datab
c0f0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
c100: 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75  is being configu
c110: 72 65 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79  red..** The only
c120: 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 69 73   choice for this
c130: 20 76 61 6c 75 65 20 69 73 20 5b 53 51 4c 49 54   value is [SQLIT
c140: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
c150: 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65  SIDE]..** New ve
c160: 72 62 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74  rbs are likely t
c170: 6f 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  o be added in fu
c180: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
c190: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69   SQLite..** Addi
c1a0: 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
c1b0: 20 64 65 70 65 6e 64 20 6f 6e 20 74 68 65 20 76   depend on the v
c1c0: 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  erb..**.** INVAR
c1d0: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
c1e0: 34 32 30 33 7d 20 41 20 63 61 6c 6c 20 74 6f 20  4203} A call to 
c1f0: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
c200: 69 67 28 44 2c 56 2c 2e 2e 2e 29 5d 20 73 68 61  ig(D,V,...)] sha
c210: 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
c220: 45 5f 4f 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20  E_OK].**        
c230: 20 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66    if and only if
c240: 20 74 68 65 20 63 61 6c 6c 20 69 73 20 73 75 63   the call is suc
c250: 63 65 73 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 7b  cessful..**.** {
c260: 48 31 34 32 30 36 7d 20 49 66 20 6f 6e 65 20 6f  H14206} If one o
c270: 72 20 6d 6f 72 65 20 73 6c 6f 74 73 20 6f 66 20  r more slots of 
c280: 74 68 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  the [lookaside m
c290: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
c2a0: 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
c2b0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
c2c0: 63 74 69 6f 6e 5d 20 44 20 61 72 65 20 69 6e 20  ction] D are in 
c2d0: 75 73 65 2c 20 74 68 65 6e 20 61 20 63 61 6c 6c  use, then a call
c2e0: 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
c2f0: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
c300: 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42  ig](D,[SQLITE_DB
c310: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
c320: 5d 2c 2e 2e 2e 29 20 73 68 61 6c 6c 0a 2a 2a 20  ],...) shall.** 
c330: 20 20 20 20 20 20 20 20 20 66 61 69 6c 20 77 69           fail wi
c340: 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55  th an [SQLITE_BU
c350: 53 59 5d 20 72 65 74 75 72 6e 20 63 6f 64 65 2e  SY] return code.
c360: 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 32 30 39 7d 20  .**.** {H14209} 
c370: 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
c380: 6c 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20  l to .**        
c390: 20 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f    [sqlite3_db_co
c3a0: 6e 66 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  nfig](D,[SQLITE_
c3b0: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
c3c0: 44 45 5d 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 65  DE],B,Z,N) where
c3d0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20 69  .**          D i
c3e0: 73 20 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61 62  s an open [datab
c3f0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
c400: 61 6e 64 20 5a 20 61 6e 64 20 4e 20 61 72 65 20  and Z and N are 
c410: 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20 20 20  positive.**     
c420: 20 20 20 20 20 69 6e 74 65 67 65 72 73 20 61 6e       integers an
c430: 64 20 42 20 69 73 20 61 6e 20 61 6c 69 67 6e 65  d B is an aligne
c440: 64 20 62 75 66 66 65 72 20 61 74 20 6c 65 61 73  d buffer at leas
c450: 74 20 5a 2a 4e 20 62 79 74 65 73 20 69 6e 20 73  t Z*N bytes in s
c460: 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ize.**          
c470: 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20  shall cause the 
c480: 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
c490: 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72  y allocator] for
c4a0: 20 44 20 74 6f 20 75 73 65 20 62 75 66 66 65 72   D to use buffer
c4b0: 20 42 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   B .**          
c4c0: 77 69 74 68 20 4e 20 73 6c 6f 74 73 20 6f 66 20  with N slots of 
c4d0: 5a 20 62 79 74 65 73 20 65 61 63 68 2e 0a 2a 2a  Z bytes each..**
c4e0: 0a 2a 2a 20 7b 48 31 34 32 31 32 7d 20 41 20 73  .** {H14212} A s
c4f0: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
c500: 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  o .**          [
c510: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
c520: 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42 43  g](D,[SQLITE_DBC
c530: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
c540: 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 65 0a 2a 2a  ,B,Z,N) where.**
c550: 20 20 20 20 20 20 20 20 20 20 44 20 69 73 20 61            D is a
c560: 6e 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  n open [database
c570: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
c580: 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 70 6f 73   Z and N are pos
c590: 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  itive.**        
c5a0: 20 20 69 6e 74 65 67 65 72 73 20 61 6e 64 20 42    integers and B
c5b0: 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
c5c0: 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65   shall cause the
c5d0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 6c 6f  .**          [lo
c5e0: 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
c5f0: 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20 44 20  llocator] for D 
c600: 74 6f 20 61 20 6f 62 74 61 69 6e 20 5a 2a 4e 20  to a obtain Z*N 
c610: 62 79 74 65 20 62 75 66 66 65 72 0a 2a 2a 20 20  byte buffer.**  
c620: 20 20 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65          from the
c630: 20 70 72 69 6d 61 72 79 20 6d 65 6d 6f 72 79 20   primary memory 
c640: 61 6c 6c 6f 63 61 74 6f 72 20 61 6e 64 20 75 73  allocator and us
c650: 65 20 74 68 61 74 20 62 75 66 66 65 72 0a 2a 2a  e that buffer.**
c660: 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 4e            with N
c670: 20 6c 6f 6f 6b 61 73 69 64 65 20 73 6c 6f 74 73   lookaside slots
c680: 20 6f 66 20 5a 20 62 79 74 65 73 20 65 61 63 68   of Z bytes each
c690: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 32 31 35 7d  ..**.** {H14215}
c6a0: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
c6b0: 6c 6c 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20  ll to .**       
c6c0: 20 20 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63     [sqlite3_db_c
c6d0: 6f 6e 66 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45  onfig](D,[SQLITE
c6e0: 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
c6f0: 49 44 45 5d 2c 42 2c 5a 2c 4e 29 20 77 68 65 72  IDE],B,Z,N) wher
c700: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20  e.**          D 
c710: 69 73 20 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61  is an open [data
c720: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
c730: 20 61 6e 64 20 5a 20 61 6e 64 20 4e 20 61 72 65   and Z and N are
c740: 20 7a 65 72 6f 20 73 68 61 6c 6c 0a 2a 2a 20 20   zero shall.**  
c750: 20 20 20 20 20 20 20 20 64 69 73 61 62 6c 65 20          disable 
c760: 74 68 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  the [lookaside m
c770: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
c780: 20 66 6f 72 20 44 2e 0a 2a 2a 0a 2a 2a 0a 2a 2f   for D..**.**.*/
c790: 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
c7a0: 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33  NTAL int sqlite3
c7b0: 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74  _db_config(sqlit
c7c0: 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e  e3*, int op, ...
c7d0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
c7e0: 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
c7f0: 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b  ation Routines {
c800: 48 31 30 31 35 35 7d 20 3c 53 32 30 31 32 30 3e  H10155} <S20120>
c810: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
c820: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
c830: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
c840: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
c850: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
c860: 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f  SQLite.** and lo
c870: 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
c880: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
c890: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f  es..**.** This o
c8a0: 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e  bject is used in
c8b0: 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20   only one place 
c8c0: 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e  in the SQLite in
c8d0: 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f  terface..** A po
c8e0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
c8f0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
c900: 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ect is the argum
c910: 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ent to.** [sqlit
c920: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65  e3_config()] whe
c930: 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
c940: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ion option is.**
c950: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
c960: 4d 41 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65  MALLOC].  By cre
c970: 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
c980: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
c990: 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
c9a0: 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
c9b0: 6f 6e 66 69 67 28 29 5d 20 64 75 72 69 6e 67 20  onfig()] during 
c9c0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
c9d0: 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  n.** application
c9e0: 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
c9f0: 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
ca00: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
ca10: 62 73 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53  bsystem.** for S
ca20: 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
ca30: 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
ca40: 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
ca50: 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
ca60: 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
ca70: 69 74 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d  ith a built-in m
ca80: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
ca90: 74 68 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 65  that is.** perfe
caa0: 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f  ctly adequate fo
cab0: 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69  r the overwhelmi
cac0: 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61  ng majority of a
cad0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61  pplications.** a
cae0: 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a  nd that this obj
caf0: 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66  ect is only usef
cb00: 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e  ul to a tiny min
cb10: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
cb20: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70  tions.** with sp
cb30: 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79  ecialized memory
cb40: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
cb50: 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20  irements.  This 
cb60: 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73  object is.** als
cb70: 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  o used during te
cb80: 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20  sting of SQLite 
cb90: 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63  in order to spec
cba0: 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
cbb0: 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
cbc0: 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75  ocator that simu
cbd0: 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74  lates memory out
cbe0: 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69  -of-memory condi
cbf0: 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65  tions in.** orde
cc00: 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74  r to verify that
cc10: 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73   SQLite recovers
cc20: 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d   gracefully from
cc30: 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69   such.** conditi
cc40: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ons..**.** The x
cc50: 4d 61 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61  Malloc, xFree, a
cc60: 6e 64 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68  nd xRealloc meth
cc70: 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69  ods must work li
cc80: 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63  ke the.** malloc
cc90: 28 29 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 20  (), free(), and 
cca0: 72 65 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69  realloc() functi
ccb0: 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61  ons from the sta
ccc0: 6e 64 61 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a  ndard library..*
ccd0: 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c  *.** xSize shoul
cce0: 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c  d return the all
ccf0: 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61  ocated size of a
cd00: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
cd10: 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  on.** previously
cd20: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78   obtained from x
cd30: 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c  Malloc or xReall
cd40: 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74  oc.  The allocat
cd50: 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c  ed size.** is al
cd60: 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73  ways at least as
cd70: 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75   big as the requ
cd80: 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d  ested size but m
cd90: 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a  ay be larger..**
cda0: 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70  .** The xRoundup
cdb0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
cdc0: 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68  what would be th
cdd0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
cde0: 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20   of.** a memory 
cdf0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e  allocation given
ce00: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
ce10: 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d  quested size.  M
ce20: 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ost memory.** al
ce30: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
ce40: 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  p memory allocat
ce50: 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f  ions at least to
ce60: 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70   the next multip
ce70: 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d  le.** of 8.  Som
ce80: 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  e allocators rou
ce90: 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65  nd up to a large
cea0: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f  r multiple or to
ceb0: 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a   a power of 2..*
cec0: 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
ced0: 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
cee0: 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
cef0: 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78  ocator.  (For ex
cf00: 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
cf10: 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
cf20: 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
cf30: 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
cf40: 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
cf50: 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
cf60: 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
cf70: 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
cf80: 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
cf90: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
cfa0: 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
cfb0: 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
cfc0: 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
cfd0: 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
cfe0: 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
cff0: 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
d000: 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
d010: 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
d020: 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a  d xShutdown..*/.
d030: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
d040: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
d050: 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ds sqlite3_mem_m
d060: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
d070: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
d080: 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ds {.  void *(*x
d090: 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20  Malloc)(int);   
d0a0: 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20        /* Memory 
d0b0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
d0c0: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ion */.  void (*
d0d0: 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20  xFree)(void*);  
d0e0: 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20          /* Free 
d0f0: 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  a prior allocati
d100: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  on */.  void *(*
d110: 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c  xRealloc)(void*,
d120: 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65  int);  /* Resize
d130: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
d140: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29  /.  int (*xSize)
d150: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
d160: 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65     /* Return the
d170: 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f   size of an allo
d180: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
d190: 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29  (*xRoundup)(int)
d1a0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f  ;          /* Ro
d1b0: 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73  und up request s
d1c0: 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f  ize to allocatio
d1d0: 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20  n size */.  int 
d1e0: 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b  (*xInit)(void*);
d1f0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e             /* In
d200: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
d210: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
d220: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64  .  void (*xShutd
d230: 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  own)(void*);    
d240: 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a    /* Deinitializ
d250: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
d260: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
d270: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
d280: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72             /* Ar
d290: 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28  gument to xInit(
d2a0: 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28  ) and xShutdown(
d2b0: 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ) */.};../*.** C
d2c0: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
d2d0: 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b  ration Options {
d2e0: 48 31 30 31 36 30 7d 20 3c 53 32 30 30 30 30 3e  H10160} <S20000>
d2f0: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
d300: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
d310: 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
d320: 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
d330: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
d340: 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
d350: 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
d360: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
d370: 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
d380: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
d390: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
d3a0: 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
d3b0: 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
d3c0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
d3d0: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
d3e0: 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
d3f0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
d400: 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
d410: 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
d420: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
d430: 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
d440: 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
d450: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
d460: 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
d470: 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
d480: 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71  worked.  The [sq
d490: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
d4a0: 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
d4b0: 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
d4c0: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
d4d0: 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
d4e0: 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
d4f0: 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
d500: 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
d510: 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
d520: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
d530: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
d540: 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
d550: 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
d560: 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
d570: 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69  tion.  This opti
d580: 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  on disables.** a
d590: 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
d5a0: 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
d5b0: 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
d5c0: 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
d5d0: 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
d5e0: 20 74 68 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a   thread.</dd>.**
d5f0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
d600: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
d610: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
d620: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
d630: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
d640: 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f  ion.  This optio
d650: 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  n disables.** mu
d660: 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
d670: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
d680: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
d690: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
d6a0: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
d6b0: 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
d6c0: 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
d6d0: 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
d6e0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
d6f0: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
d700: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
d710: 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
d720: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
d730: 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
d740: 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
d750: 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
d760: 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
d770: 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
d780: 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
d790: 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
d7a0: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
d7b0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
d7c0: 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
d7d0: 65 20 74 69 6d 65 2e 20 20 53 65 65 20 74 68 65  e time.  See the
d7e0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
d7f0: 5d 0a 2a 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69  ].** documentati
d800: 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
d810: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f  l information.</
d820: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
d830: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
d840: 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
d850: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
d860: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
d870: 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20  s option.  This 
d880: 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
d890: 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
d8a0: 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
d8b0: 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
d8c0: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
d8d0: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
d8e0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
d8f0: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
d900: 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
d910: 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
d920: 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
d930: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
d940: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
d950: 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c  SAFE=1]) the SQL
d960: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
d970: 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
d980: 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
d990: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d9a0: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
d9b0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
d9c0: 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
d9d0: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
d9e0: 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
d9f0: 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
da00: 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
da10: 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
da20: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
da30: 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
da40: 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
da50: 6d 65 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b  me..** See the [
da60: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
da70: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
da80: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
da90: 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  ormation.</dd>.*
daa0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
dab0: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
dac0: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
dad0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
dae0: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
daf0: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
db00: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
db10: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
db20: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
db30: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
db40: 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
db50: 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
db60: 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
db70: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
db80: 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
db90: 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
dba0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
dbb0: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
dbc0: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
dbd0: 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  e.</dd>.**.** <d
dbe0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
dbf0: 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
dc00: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
dc10: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
dc20: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
dc30: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
dc40: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
dc50: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
dc60: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
dc70: 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c  cture.  The [sql
dc80: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
dc90: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
dca0: 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
dcb0: 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
dcc0: 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
dcd0: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a  ation routines..
dce0: 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
dcf0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
dd00: 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
dd10: 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
dd20: 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
dd30: 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
dd40: 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73  that simulations
dd50: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
dd60: 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a  on failure or.**
dd70: 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75   tracks memory u
dd80: 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c  sage, for exampl
dd90: 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  e.</dd>.**.** <d
dda0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
ddb0: 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a  MEMSTATUS</dt>.*
ddc0: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
ddd0: 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
dde0: 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
ddf0: 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
de00: 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61   as a .** boolea
de10: 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
de20: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
de30: 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d   collection of m
de40: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
de50: 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e   .** statistics.
de60: 20 57 68 65 6e 20 64 69 73 61 62 6c 65 64 2c 20   When disabled, 
de70: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  the following SQ
de80: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
de90: 62 65 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e 2d 6f  become .** non-o
dea0: 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
deb0: 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
dec0: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
ded0: 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
dee0: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
def0: 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
df00: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
df10: 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
df20: 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  t()].**   <li> [
df30: 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29  sqlite3_status()
df40: 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20  ].**   </ul>.** 
df50: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
df60: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
df70: 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RATCH</dt>.** <d
df80: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70  d>This option sp
df90: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
dfa0: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
dfb0: 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
dfc0: 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63  se for.** scratc
dfd0: 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65  h memory.  There
dfe0: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
dff0: 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72  ents:  A pointer
e000: 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20   to the memory, 
e010: 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
e020: 61 63 68 20 73 63 72 61 74 63 68 20 62 75 66 66  ach scratch buff
e030: 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65  er (sz), and the
e040: 20 6e 75 6d 62 65 72 20 6f 66 20 62 75 66 66 65   number of buffe
e050: 72 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a  rs (N).  The sz.
e060: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
e070: 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f   be a multiple o
e080: 66 20 31 36 2e 20 54 68 65 20 73 7a 20 70 61 72  f 16. The sz par
e090: 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65  ameter should be
e0a0: 20 61 20 66 65 77 20 62 79 74 65 73 0a 2a 2a 20   a few bytes.** 
e0b0: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
e0c0: 61 63 74 75 61 6c 20 73 63 72 61 74 63 68 20 73  actual scratch s
e0d0: 70 61 63 65 20 72 65 71 75 69 72 65 64 20 64 75  pace required du
e0e0: 65 20 69 6e 74 65 72 6e 61 6c 20 6f 76 65 72 68  e internal overh
e0f0: 65 61 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  ead..** The firs
e100: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  t.** argument sh
e110: 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e  ould point to an
e120: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61   allocation of a
e130: 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
e140: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
e150: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
e160: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e   no more than on
e170: 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  e scratch buffer
e180: 20 61 74 20 6f 6e 63 65 20 70 65 72 20 74 68 72   at once per thr
e190: 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f  ead, so.** N sho
e1a0: 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 68  uld be set to th
e1b0: 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d  e expected maxim
e1c0: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72  um number of thr
e1d0: 65 61 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a 2a  eads.  The sz.**
e1e0: 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c   parameter shoul
e1f0: 64 20 62 65 20 36 20 74 69 6d 65 73 20 74 68 65  d be 6 times the
e200: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
e210: 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
e220: 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 61  ge size..** Scra
e230: 74 63 68 20 62 75 66 66 65 72 73 20 61 72 65 20  tch buffers are 
e240: 75 73 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  used as part of 
e250: 74 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63  the btree balanc
e260: 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49 66  e operation.  If
e270: 0a 2a 2a 20 54 68 65 20 62 74 72 65 65 20 62 61  .** The btree ba
e280: 6c 61 6e 63 65 72 20 6e 65 65 64 73 20 61 64 64  lancer needs add
e290: 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 62  itional memory b
e2a0: 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
e2b0: 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20 73 63 72  ovided by.** scr
e2c0: 61 74 63 68 20 62 75 66 66 65 72 73 20 6f 72 20  atch buffers or 
e2d0: 69 66 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75  if no scratch bu
e2e0: 66 66 65 72 20 73 70 61 63 65 20 69 73 20 73 70  ffer space is sp
e2f0: 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 53 51  ecified, then SQ
e300: 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f 20  Lite.** goes to 
e310: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
e320: 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  )] to obtain the
e330: 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65 64 73   memory it needs
e340: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
e350: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
e360: 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  AGECACHE</dt>.**
e370: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
e380: 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
e390: 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
e3a0: 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
e3b0: 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65  n use for.** the
e3c0: 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
e3d0: 61 63 68 65 2e 20 20 54 68 65 72 65 20 61 72 65  ache.  There are
e3e0: 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
e3f0: 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  : A pointer to t
e400: 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68  he.** memory, th
e410: 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70  e size of each p
e420: 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c  age buffer (sz),
e430: 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
e440: 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a  of pages (N)..**
e450: 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
e460: 20 6d 75 73 74 20 62 65 20 61 20 70 6f 77 65 72   must be a power
e470: 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
e480: 35 31 32 20 61 6e 64 20 33 32 37 36 38 2e 20 20  512 and 32768.  
e490: 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
e4a0: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
e4b0: 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74  nt to an allocat
e4c0: 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ion of at least 
e4d0: 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
e4e0: 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  mory..** SQLite 
e4f0: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
e500: 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
e510: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
e520: 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
e530: 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
e540: 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
e550: 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
e560: 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
e570: 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
e580: 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
e590: 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
e5a0: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
e5b0: 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74  ided by this opt
e5c0: 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  ion, then.** SQL
e5d0: 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
e5e0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66  ite3_malloc()] f
e5f0: 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61  or the additiona
e600: 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e  l storage space.
e610: 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  .** The implemen
e620: 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 75 73 65  tation might use
e630: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
e640: 74 68 65 20 4e 20 62 75 66 66 65 72 73 20 74 6f  the N buffers to
e650: 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72 79   hold .** memory
e660: 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 6e 66 6f   accounting info
e670: 72 6d 61 74 69 6f 6e 2e 20 3c 2f 64 64 3e 0a 2a  rmation. </dd>.*
e680: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
e690: 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e  CONFIG_HEAP</dt>
e6a0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
e6b0: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
e6c0: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
e6d0: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
e6e0: 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72   will use.** for
e6f0: 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
e700: 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  mic memory alloc
e710: 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f  ation needs beyo
e720: 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65  nd those provide
e730: 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c  d.** for by [SQL
e740: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
e750: 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  CH] and [SQLITE_
e760: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
e770: 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  ]..** There are 
e780: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
e790: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   A pointer to th
e7a0: 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 6e 75  e memory, the nu
e7b0: 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
e7c0: 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62   in the memory b
e7d0: 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d  uffer, and the m
e7e0: 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
e7f0: 6e 20 73 69 7a 65 2e 20 20 49 66 0a 2a 2a 20 74  n size.  If.** t
e800: 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
e810: 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
e820: 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74  nter) is NULL, t
e830: 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72  hen SQLite rever
e840: 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69  ts.** to using i
e850: 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  ts default memor
e860: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65  y allocator (the
e870: 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
e880: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29   implementation)
e890: 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79  ,.** undoing any
e8a0: 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f   prior invocatio
e8b0: 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  n of [SQLITE_CON
e8c0: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 49 66  FIG_MALLOC].  If
e8d0: 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
e8e0: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
e8f0: 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53  LL and either [S
e900: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
e910: 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  SYS3] or.** [SQL
e920: 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
e930: 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c  S5] are defined,
e940: 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
e950: 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
e960: 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
e970: 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
e980: 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
e990: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e9a0: 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  needs.</dd>.**.*
e9b0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
e9c0: 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  FIG_MUTEX</dt>.*
e9d0: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
e9e0: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
e9f0: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
ea00: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
ea10: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
ea20: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
ea30: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
ea40: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
ea50: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
ea60: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
ea70: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20  low-level mutex 
ea80: 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
ea90: 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20  sed in place.** 
eaa0: 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  the mutex routin
eab0: 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
eac0: 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Lite.</dd>.**.**
ead0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
eae0: 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
eaf0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
eb00: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
eb10: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
eb20: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
eb30: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
eb40: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
eb50: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
eb60: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
eb70: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
eb80: 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
eb90: 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
eba0: 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
ebb0: 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
ebc0: 65 78 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  ex routines..** 
ebd0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
ebe0: 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
ebf0: 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
ec00: 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e  mutex allocation
ec10: 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
ec20: 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64  h a wrapper used
ec30: 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20   to track mutex 
ec40: 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72  usage for perfor
ec50: 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69  mance.** profili
ec60: 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66  ng or testing, f
ec70: 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e  or example.</dd>
ec80: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
ec90: 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
eca0: 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  DE</dt>.** <dd>T
ecb0: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
ecc0: 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74   two arguments t
ecd0: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
ece0: 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d  e default.** mem
ecf0: 6f 72 79 20 61 6c 6c 63 61 74 69 6f 6e 20 6c 6f  ory allcation lo
ed00: 6f 6b 61 73 69 64 65 20 6f 70 74 69 6d 69 7a 61  okaside optimiza
ed10: 74 69 6f 6e 2e 20 20 54 68 65 20 66 69 72 73 74  tion.  The first
ed20: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
ed30: 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
ed40: 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
ed50: 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73  r slot and the s
ed60: 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d  econd is the num
ed70: 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20  ber of.** slots 
ed80: 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63  allocated to eac
ed90: 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
eda0: 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ction.</dd>.**.*
edb0: 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
edc0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
edd0: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31  _SINGLETHREAD  1
ede0: 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
edf0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
ee00: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20  G_MULTITHREAD   
ee10: 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  2  /* nil */.#de
ee20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
ee30: 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20  IG_SERIALIZED   
ee40: 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   3  /* nil */.#d
ee50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
ee60: 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  FIG_MALLOC      
ee70: 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    4  /* sqlite3_
ee80: 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
ee90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
eea0: 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
eeb0: 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
eec0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
eed0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
eee0: 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
eef0: 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64        6  /* void
ef00: 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
ef10: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
ef20: 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
ef30: 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f  CHE     7  /* vo
ef40: 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
ef50: 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
ef60: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
ef70: 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20            8  /* 
ef80: 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65  void*, int nByte
ef90: 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65  , int min */.#de
efa0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
efb0: 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20  IG_MEMSTATUS    
efc0: 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a   9  /* boolean *
efd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
efe0: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20  _CONFIG_MUTEX   
eff0: 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69       10  /* sqli
f000: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
f010: 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
f020: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
f030: 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20  UTEX     11  /* 
f040: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
f050: 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65  thods* */./* pre
f060: 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43  viously SQLITE_C
f070: 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43  ONFIG_CHUNKALLOC
f080: 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77   12 which is now
f090: 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65   unused. */ .#de
f0a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
f0b0: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
f0c0: 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a  13  /* int int *
f0d0: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
f0e0: 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
f0f0: 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31 37 30   Options {H10170
f100: 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58  } <S20000>.** EX
f110: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
f120: 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
f130: 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
f140: 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
f150: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
f160: 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
f170: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
f180: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
f190: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
f1a0: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
f1b0: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
f1c0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
f1d0: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
f1e0: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
f1f0: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
f200: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
f210: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
f220: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
f230: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
f240: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
f250: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
f260: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
f270: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
f280: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
f290: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
f2a0: 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
f2b0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
f2c0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
f2d0: 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
f2e0: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
f2f0: 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
f300: 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
f310: 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
f320: 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
f330: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
f340: 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
f350: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
f360: 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
f370: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
f380: 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
f390: 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
f3a0: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
f3b0: 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
f3c0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
f3d0: 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
f3e0: 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
f3f0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
f400: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
f410: 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
f420: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
f430: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
f440: 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
f450: 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
f460: 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f  buffer to use fo
f470: 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  r lookaside memo
f480: 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ry.  The first.*
f490: 2a 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62  * argument may b
f4a0: 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
f4b0: 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
f4c0: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 6c 6f   allocate the lo
f4d0: 6f 6b 61 73 69 64 65 0a 2a 2a 20 62 75 66 66 65  okaside.** buffe
f4e0: 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
f4f0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
f500: 5d 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ].  The second a
f510: 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
f520: 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
f530: 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
f540: 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 74 68 69  slot and the thi
f550: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
f560: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
f570: 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
f580: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
f590: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
f5a0: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
f5b0: 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
f5c0: 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
f5d0: 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
f5e0: 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
f5f0: 75 6d 65 6e 74 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  uments.</dd>.**.
f600: 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
f610: 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
f620: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
f630: 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20   1001  /* void* 
f640: 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a  int int */.../*.
f650: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
f660: 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
f670: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
f680: 6f 64 65 73 20 7b 48 31 32 32 30 30 7d 20 3c 53  odes {H12200} <S
f690: 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  10700>.**.** The
f6a0: 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
f6b0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
f6c0: 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
f6d0: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
f6e0: 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
f6f0: 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
f700: 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 54  ure of SQLite. T
f710: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
f720: 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
f730: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
f740: 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
f750: 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
f760: 20 63 6f 6e 73 69 64 65 72 61 74 69 6f 6e 73 2e   considerations.
f770: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
f780: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 30 31  S:.**.** {H12201
f790: 7d 20 45 61 63 68 20 6e 65 77 20 5b 64 61 74 61  } Each new [data
f7a0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
f7b0: 20 73 68 61 6c 6c 20 68 61 76 65 20 74 68 65 0a   shall have the.
f7c0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 74  **          [ext
f7d0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
f7e0: 65 73 5d 20 66 65 61 74 75 72 65 20 64 69 73 61  es] feature disa
f7f0: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
f800: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 30 32 7d 20  .**.** {H12202} 
f810: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  The [sqlite3_ext
f820: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
f830: 65 73 28 44 2c 46 29 5d 20 69 6e 74 65 72 66 61  es(D,F)] interfa
f840: 63 65 20 73 68 61 6c 6c 20 65 6e 61 62 6c 65 0a  ce shall enable.
f850: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 74  **          [ext
f860: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
f870: 65 73 5d 20 66 6f 72 20 74 68 65 20 20 5b 64 61  es] for the  [da
f880: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f890: 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20  n] D.**         
f8a0: 20 69 66 20 74 68 65 20 46 20 70 61 72 61 6d 65   if the F parame
f8b0: 74 65 72 20 69 73 20 74 72 75 65 2c 20 6f 72 20  ter is true, or 
f8c0: 64 69 73 61 62 6c 65 20 74 68 65 6d 20 69 66 20  disable them if 
f8d0: 46 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69  F is false..*/.i
f8e0: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
f8f0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
f900: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
f910: 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
f920: 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
f930: 65 72 74 20 52 6f 77 69 64 20 7b 48 31 32 32 32  ert Rowid {H1222
f940: 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a  0} <S10700>.**.*
f950: 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20  * Each entry in 
f960: 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
f970: 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
f980: 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
f990: 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
f9a0: 20 74 68 65 20 22 72 6f 77 69 64 22 2e 20 54 68   the "rowid". Th
f9b0: 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
f9c0: 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
f9d0: 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
f9e0: 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
f9f0: 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
fa00: 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
fa10: 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
fa20: 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
fa30: 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
fa40: 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
fa50: 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
fa60: 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
fa70: 74 79 70 65 20 49 4e 54 45 47 45 52 20 50 52 49  type INTEGER PRI
fa80: 4d 41 52 59 20 4b 45 59 20 74 68 65 6e 20 74 68  MARY KEY then th
fa90: 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
faa0: 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
fab0: 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
fac0: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
fad0: 72 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69  returns the rowi
fae0: 64 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65  d of the most re
faf0: 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66  cent.** successf
fb00: 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
fb10: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
fb20: 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  om the [database
fb30: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
fb40: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
fb50: 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75  ument.  If no su
fb60: 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
fb70: 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20  ]s.** have ever 
fb80: 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74  occurred on that
fb90: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
fba0: 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65  tion, zero is re
fbb0: 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  turned..**.** If
fbc0: 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63   an [INSERT] occ
fbd0: 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
fbe0: 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72  gger, then the r
fbf0: 6f 77 69 64 20 6f 66 20 74 68 65 20 69 6e 73 65  owid of the inse
fc00: 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72  rted.** row is r
fc10: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
fc20: 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20  routine as long 
fc30: 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69  as the trigger i
fc40: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75  s running..** Bu
fc50: 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67  t once the trigg
fc60: 65 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74  er terminates, t
fc70: 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
fc80: 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  d by this routin
fc90: 65 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20  e.** reverts to 
fca0: 74 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69  the last value i
fcb0: 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65 20 74  nserted before t
fcc0: 68 65 20 74 72 69 67 67 65 72 20 66 69 72 65 64  he trigger fired
fcd0: 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 49 4e 53 45  ..**.** An [INSE
fce0: 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64  RT] that fails d
fcf0: 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69  ue to a constrai
fd00: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20  nt violation is 
fd10: 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73  not a.** success
fd20: 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64  ful [INSERT] and
fd30: 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
fd40: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
fd50: 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
fd60: 6f 75 74 69 6e 65 2e 20 20 54 68 75 73 20 49 4e  outine.  Thus IN
fd70: 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
fd80: 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
fd90: 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
fda0: 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
fdb0: 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
fdc0: 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
fdd0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
fde0: 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
fdf0: 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
fe00: 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57  ertion fails.  W
fe10: 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
fe20: 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
fe30: 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
fe40: 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
fe50: 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
fe60: 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
fe70: 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
fe80: 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
fe90: 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
fea0: 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
feb0: 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
fec0: 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
fed0: 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
fee0: 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
fef0: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
ff00: 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
ff10: 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70  .** For the purp
ff20: 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
ff30: 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54  tine, an [INSERT
ff40: 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  ] is considered 
ff50: 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73  to.** be success
ff60: 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69  ful even if it i
ff70: 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72  s subsequently r
ff80: 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
ff90: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
ffa0: 0a 2a 2a 20 7b 48 31 32 32 32 31 7d 20 54 68 65  .** {H12221} The
ffb0: 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
ffc0: 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 66  nsert_rowid()] f
ffd0: 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65  unction shall re
ffe0: 74 75 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a  turn the rowid.*
fff0: 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
10000 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75  e most recent su
10010 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
10020 5d 20 70 65 72 66 6f 72 6d 65 64 20 6f 6e 20 74  ] performed on t
10030 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he same.**      
10040 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
10050 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 77 69  nnection] and wi
10060 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  thin the same or
10070 20 68 69 67 68 65 72 20 6c 65 76 65 6c 0a 2a 2a   higher level.**
10080 20 20 20 20 20 20 20 20 20 20 74 72 69 67 67 65            trigge
10090 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65  r context, or ze
100a0 72 6f 20 69 66 20 74 68 65 72 65 20 68 61 76 65  ro if there have
100b0 20 62 65 65 6e 20 6e 6f 20 71 75 61 6c 69 66 79   been no qualify
100c0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
100d0 5b 49 4e 53 45 52 54 5d 20 73 74 61 74 65 6d 65  [INSERT] stateme
100e0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  nts..**.** {H122
100f0 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  23} The [sqlite3
10100 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
10110 69 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73  id()] function s
10120 68 61 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 0a  hall return the.
10130 2a 2a 20 20 20 20 20 20 20 20 20 20 73 61 6d 65  **          same
10140 20 76 61 6c 75 65 20 77 68 65 6e 20 63 61 6c 6c   value when call
10150 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
10160 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
10170 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6d 6d  .**          imm
10180 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20  ediately before 
10190 61 6e 64 20 61 66 74 65 72 20 61 20 5b 52 4f 4c  and after a [ROL
101a0 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53  LBACK]..**.** AS
101b0 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  SUMPTIONS:.**.**
101c0 20 7b 41 31 32 32 33 32 7d 20 49 66 20 61 20 73   {A12232} If a s
101d0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
101e0 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
101f0 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
10200 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  me.**          d
10210 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10220 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71  on while the [sq
10230 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
10240 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 20 20  t_rowid()].**   
10250 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20         function 
10260 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
10270 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
10280 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69  last insert rowi
10290 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  d,.**          t
102a0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
102b0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
102c0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
102d0 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 20 20  owid()] is.**   
102e0 20 20 20 20 20 20 20 75 6e 70 72 65 64 69 63 74         unpredict
102f0 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
10300 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
10310 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
10320 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c  ew.**          l
10330 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64  ast insert rowid
10340 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
10350 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  64 sqlite3_last_
10360 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
10370 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
10380 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
10390 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
103a0 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32  s Modified {H122
103b0 34 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a  40} <S10600>.**.
103c0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
103d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
103e0 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20  ber of database 
103f0 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63  rows that were c
10400 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73  hanged.** or ins
10410 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
10420 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
10430 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
10440 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
10450 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
10460 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
10470 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
10480 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
10490 2a 2a 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20  ** Only changes 
104a0 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c  that are directl
104b0 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  y specified by t
104c0 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50  he [INSERT], [UP
104d0 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45  DATE],.** or [DE
104e0 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20  LETE] statement 
104f0 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75  are counted.  Au
10500 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20  xiliary changes 
10510 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69  caused by.** tri
10520 67 67 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f  ggers are not co
10530 75 6e 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b  unted. Use the [
10540 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
10550 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
10560 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65  n.** to find the
10570 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
10580 20 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69   changes includi
10590 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ng changes cause
105a0 64 20 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a  d by triggers..*
105b0 2a 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68 61 6e  *.** A "row chan
105c0 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20  ge" is a change 
105d0 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  to a single row 
105e0 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c  of a single tabl
105f0 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61  e.** caused by a
10600 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45  n INSERT, DELETE
10610 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74  , or UPDATE stat
10620 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61  ement.  Rows tha
10630 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64  t.** are changed
10640 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73   as side effects
10650 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73   of REPLACE cons
10660 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
10670 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20  n,.** rollback, 
10680 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
10690 2c 20 44 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72  , DROP TABLE, or
106a0 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a   by any other.**
106b0 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e   mechanisms do n
106c0 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65  ot count as dire
106d0 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a  ct row changes..
106e0 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72  **.** A "trigger
106f0 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73   context" is a s
10700 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f  cope of executio
10710 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e  n that begins an
10720 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74  d.** ends with t
10730 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 74  he script of a t
10740 72 69 67 67 65 72 2e 20 20 4d 6f 73 74 20 53 51  rigger.  Most SQ
10750 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
10760 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75  .** evaluated ou
10770 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69  tside of any tri
10780 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74  gger.  This is t
10790 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a  he "top level".*
107a0 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
107b0 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72  t.  If a trigger
107c0 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20   fires from the 
107d0 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20  top level, a.** 
107e0 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
107f0 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66  ext is entered f
10800 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20  or the duration 
10810 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74  of that one.** t
10820 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67  rigger.  Subtrig
10830 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63  gers create subc
10840 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69  ontexts for thei
10850 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  r duration..**.*
10860 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * Calling [sqlit
10870 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73  e3_exec()] or [s
10880 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
10890 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a  ecursively does.
108a0 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20  ** not create a 
108b0 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
108c0 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ext..**.** This 
108d0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
108e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
108f0 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
10900 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74  s in the.** most
10910 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
10920 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
10930 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
10940 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74  in the same.** t
10950 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
10960 2a 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e  **.** Thus, when
10970 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
10980 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73   top level, this
10990 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
109a0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
109b0 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  of changes in th
109c0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
109d0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
109e0 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
109f0 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74  also occurred at
10a00 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20   the top level. 
10a10 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79   Within the body
10a20 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a   of a trigger,.*
10a30 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  * the sqlite3_ch
10a40 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63  anges() interfac
10a50 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
10a60 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
10a70 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73  er of.** changes
10a80 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
10a90 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
10aa0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
10ab0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
10ac0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
10ad0 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61  e body of the sa
10ae0 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48  me trigger..** H
10af0 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62  owever, the numb
10b00 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  er returned does
10b10 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
10b20 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62  nges.** caused b
10b30 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69  y subtriggers si
10b40 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74  nce those have t
10b50 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74  heir own context
10b60 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
10b70 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f  mplements the co
10b80 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52  mmand "DELETE FR
10b90 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75  OM table" withou
10ba0 74 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65  t a WHERE clause
10bb0 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20  .** by dropping 
10bc0 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74  and recreating t
10bd0 68 65 20 74 61 62 6c 65 2e 20 20 44 6f 69 6e 67  he table.  Doing
10be0 20 73 6f 20 69 73 20 6d 75 63 68 20 66 61 73 74   so is much fast
10bf0 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a  er than going.**
10c00 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c   through and del
10c10 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c  eting individual
10c20 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74   elements from t
10c30 68 65 20 74 61 62 6c 65 2e 20 20 42 65 63 61 75  he table.  Becau
10c40 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70  se of this.** op
10c50 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20  timization, the 
10c60 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20 22 44 45  deletions in "DE
10c70 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22  LETE FROM table"
10c80 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 63 68 61   are not row cha
10c90 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c  nges and.** will
10ca0 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20   not be counted 
10cb0 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  by the sqlite3_c
10cc0 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 73 71 6c  hanges() or [sql
10cd0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
10ce0 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  es()].** functio
10cf0 6e 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ns, regardless o
10d00 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
10d10 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65  elements that we
10d20 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  re originally.**
10d30 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20 20   in the table.  
10d40 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61  To get an accura
10d50 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20  te count of the 
10d60 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64  number of rows d
10d70 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22  eleted, use.** "
10d80 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
10d90 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65  e WHERE 1" inste
10da0 61 64 2e 20 20 4f 72 20 72 65 63 6f 6d 70 69 6c  ad.  Or recompil
10db0 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
10dc0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 55 4e  SQLITE_OMIT_TRUN
10dd0 43 41 54 45 5f 4f 50 54 49 4d 49 5a 41 54 49 4f  CATE_OPTIMIZATIO
10de0 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  N] compile-time 
10df0 6f 70 74 69 6f 6e 20 74 6f 20 64 69 73 61 62 6c  option to disabl
10e00 65 20 74 68 65 0a 2a 2a 20 6f 70 74 69 6d 69 7a  e the.** optimiz
10e10 61 74 69 6f 6e 20 6f 6e 20 61 6c 6c 20 71 75 65  ation on all que
10e20 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ries..**.** INVA
10e30 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
10e40 31 32 32 34 31 7d 20 54 68 65 20 5b 73 71 6c 69  12241} The [sqli
10e50 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  te3_changes()] f
10e60 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65  unction shall re
10e70 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
10e80 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  of.**          r
10e90 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ow changes cause
10ea0 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
10eb0 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
10ec0 41 54 45 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ATE,.**         
10ed0 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
10ee0 6d 65 6e 74 20 6f 6e 20 74 68 65 20 73 61 6d 65  ment on the same
10ef0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
10f00 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20  tion and.**     
10f10 20 20 20 20 20 77 69 74 68 69 6e 20 74 68 65 20       within the 
10f20 73 61 6d 65 20 6f 72 20 68 69 67 68 65 72 20 74  same or higher t
10f30 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20  rigger context, 
10f40 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65  or zero if there
10f50 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20   have.**        
10f60 20 20 6e 6f 74 20 62 65 65 6e 20 61 6e 79 20 71    not been any q
10f70 75 61 6c 69 66 79 69 6e 67 20 72 6f 77 20 63 68  ualifying row ch
10f80 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  anges..**.** {H1
10f90 32 32 34 33 7d 20 53 74 61 74 65 6d 65 6e 74 73  2243} Statements
10fa0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45   of the form "DE
10fb0 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e  LETE FROM tablen
10fc0 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20  ame" with no.** 
10fd0 20 20 20 20 20 20 20 20 20 57 48 45 52 45 20 63           WHERE c
10fe0 6c 61 75 73 65 20 73 68 61 6c 6c 20 63 61 75 73  lause shall caus
10ff0 65 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  e subsequent cal
11000 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ls to.**        
11010 20 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67    [sqlite3_chang
11020 65 73 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20  es()] to return 
11030 7a 65 72 6f 2c 20 72 65 67 61 72 64 6c 65 73 73  zero, regardless
11040 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
11050 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f      number of ro
11060 77 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e  ws originally in
11070 20 74 68 65 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a   the table..**.*
11080 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a  * ASSUMPTIONS:.*
11090 2a 0a 2a 2a 20 7b 41 31 32 32 35 32 7d 20 49 66  *.** {A12252} If
110a0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
110b0 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
110c0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
110d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
110e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69  .**          whi
110f0 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
11100 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
11110 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
11120 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20   returned.**    
11130 20 20 20 20 20 20 69 73 20 75 6e 70 72 65 64 69        is unpredi
11140 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
11150 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
11160 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
11170 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
11180 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
11190 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
111a0 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 32  ws Modified {H12
111b0 32 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a  260} <S10600>.**
111c0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
111d0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
111e0 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e  mber of row chan
111f0 67 65 73 20 63 61 75 73 65 64 20 62 79 20 49 4e  ges caused by IN
11200 53 45 52 54 2c 0a 2a 2a 20 55 50 44 41 54 45 20  SERT,.** UPDATE 
11210 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
11220 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b  ents since the [
11230 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11240 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e  ion] was opened.
11250 0a 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20 69 6e  .** The count in
11260 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67  cludes all chang
11270 65 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72 69 67  es from all trig
11280 67 65 72 20 63 6f 6e 74 65 78 74 73 2e 20 20 48  ger contexts.  H
11290 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63  owever,.** the c
112a0 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
112b0 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73  clude changes us
112c0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
112d0 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69  REPLACE constrai
112e0 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62  nts,.** do rollb
112f0 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72  acks or ABORT pr
11300 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 44 52 4f  ocessing, or DRO
11310 50 20 74 61 62 6c 65 20 70 72 6f 63 65 73 73 69  P table processi
11320 6e 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67  ng..** The chang
11330 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61  es are counted a
11340 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 74  s soon as the st
11350 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b  atement that mak
11360 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f  es them is.** co
11370 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68  mpleted (when th
11380 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
11390 6c 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 20  le is passed to 
113a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
113b0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
113c0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a  _finalize()])..*
113d0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c  *.** SQLite impl
113e0 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61  ements the comma
113f0 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  nd "DELETE FROM 
11400 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61  table" without a
11410 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a   WHERE clause.**
11420 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64   by dropping and
11430 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20   recreating the 
11440 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73  table.  (This is
11450 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 61   much faster tha
11460 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75  n going.** throu
11470 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20  gh and deleting 
11480 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65  individual eleme
11490 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62  nts from the tab
114a0 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66  le.)  Because of
114b0 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a   this.** optimiz
114c0 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74  ation, the delet
114d0 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 45 20  ions in "DELETE 
114e0 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20  FROM table" are 
114f0 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20  not row changes 
11500 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  and.** will not 
11510 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20 74 68  be counted by th
11520 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
11530 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  s() or [sqlite3_
11540 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
11550 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72  .** functions, r
11560 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
11570 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65   number of eleme
11580 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72  nts that were or
11590 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74  iginally.** in t
115a0 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 67 65  he table.  To ge
115b0 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f  t an accurate co
115c0 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  unt of the numbe
115d0 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65  r of rows delete
115e0 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54  d, use.** "DELET
115f0 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45  E FROM table WHE
11600 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 20 20  RE 1" instead.  
11610 20 4f 72 20 72 65 63 6f 6d 70 69 6c 65 20 75 73   Or recompile us
11620 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
11630 54 45 5f 4f 4d 49 54 5f 54 52 55 4e 43 41 54 45  TE_OMIT_TRUNCATE
11640 5f 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 5d 20 63  _OPTIMIZATION] c
11650 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
11660 6f 6e 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68  on to disable th
11670 65 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f  e.** optimizatio
11680 6e 20 6f 6e 20 61 6c 6c 20 71 75 65 72 69 65 73  n on all queries
11690 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
116a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
116b0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
116c0 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ce..**.** INVARI
116d0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
116e0 32 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  261} The [sqlite
116f0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
11700 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20 74  )] returns the t
11710 6f 74 61 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 20  otal number.**  
11720 20 20 20 20 20 20 20 20 6f 66 20 72 6f 77 20 63          of row c
11730 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
11740 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
11750 20 61 6e 64 2f 6f 72 20 44 45 4c 45 54 45 0a 2a   and/or DELETE.*
11760 2a 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65  *          state
11770 6d 65 6e 74 73 20 6f 6e 20 74 68 65 20 73 61 6d  ments on the sam
11780 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
11790 65 63 74 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a  ection], in any.
117a0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 72 69 67  **          trig
117b0 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e  ger context, sin
117c0 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ce the database 
117d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 63  connection was c
117e0 72 65 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  reated..**.** {H
117f0 31 32 32 36 33 7d 20 53 74 61 74 65 6d 65 6e 74  12263} Statement
11800 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44  s of the form "D
11810 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65  ELETE FROM table
11820 6e 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a  name" with no.**
11830 20 20 20 20 20 20 20 20 20 20 57 48 45 52 45 20            WHERE 
11840 63 6c 61 75 73 65 20 73 68 61 6c 6c 20 6e 6f 74  clause shall not
11850 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
11860 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20  e returned.**   
11870 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74         by [sqlit
11880 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
11890 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  ()]..**.** ASSUM
118a0 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
118b0 31 32 32 36 34 7d 20 49 66 20 61 20 73 65 70 61  12264} If a sepa
118c0 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
118d0 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
118e0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
118f0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  onnection.**    
11900 20 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c        while [sql
11910 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
11920 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
11930 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
11940 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
11950 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63  rned is unpredic
11960 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
11970 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
11980 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
11990 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
119a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
119b0 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
119c0 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
119d0 79 20 7b 48 31 32 32 37 30 7d 20 3c 53 33 30 35  y {H12270} <S305
119e0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  00>.**.** This f
119f0 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
11a00 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
11a10 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
11a20 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
11a30 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
11a40 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
11a50 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
11a60 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
11a70 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
11a80 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
11a90 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
11aa0 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
11ab0 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
11ac0 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
11ad0 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
11ae0 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
11af0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
11b00 0a 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20 74  .** It is safe t
11b10 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
11b20 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61  ine from a threa
11b30 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  d different from
11b40 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74   the.** thread t
11b50 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  hat is currently
11b60 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74   running the dat
11b70 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e  abase operation.
11b80 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e    But it.** is n
11b90 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  ot safe to call 
11ba0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
11bb0 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
11bc0 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a  nnection] that.*
11bd0 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d  * is closed or m
11be0 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72  ight close befor
11bf0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
11c00 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a  upt() returns..*
11c10 2a 0a 2a 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f  *.** If an SQL o
11c20 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79  peration is very
11c30 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64   nearly finished
11c40 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
11c50 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74  n.** sqlite3_int
11c60 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c  errupt() is call
11c70 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68  ed, then it migh
11c80 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70  t not have an op
11c90 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20  portunity.** to 
11ca0 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  be interrupted a
11cb0 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75  nd might continu
11cc0 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  e to completion.
11cd0 0a 2a 2a 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70  .**.** An SQL op
11ce0 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
11cf0 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
11d00 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
11d10 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49  INTERRUPT]..** I
11d20 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
11d30 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
11d40 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
11d50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
11d60 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
11d70 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
11d80 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
11d90 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
11da0 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
11db0 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
11dc0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
11dd0 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
11de0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
11df0 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f   has no effect o
11e00 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  n SQL statements
11e10 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
11e20 72 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  rted after sqlit
11e30 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
11e40 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e  eturns..**.** IN
11e50 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
11e60 7b 48 31 32 32 37 31 7d 20 54 68 65 20 5b 73 71  {H12271} The [sq
11e70 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
11e80 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
11e90 6c 20 66 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e  l force all runn
11ea0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
11eb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
11ec0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
11ed0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
11ee0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20   connection.**  
11ef0 20 20 20 20 20 20 20 20 74 6f 20 68 61 6c 74 20          to halt 
11f00 61 66 74 65 72 20 70 72 6f 63 65 73 73 69 6e 67  after processing
11f10 20 61 74 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64   at most one add
11f20 69 74 69 6f 6e 61 6c 20 72 6f 77 20 6f 66 20 64  itional row of d
11f30 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  ata..**.** {H122
11f40 37 32 7d 20 41 6e 79 20 53 51 4c 20 73 74 61 74  72} Any SQL stat
11f50 65 6d 65 6e 74 20 74 68 61 74 20 69 73 20 69 6e  ement that is in
11f60 74 65 72 72 75 70 74 65 64 20 62 79 20 5b 73 71  terrupted by [sq
11f70 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
11f80 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  )].**          w
11f90 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
11fa0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
11fb0 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
11fc0 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 37 39 7d  :.**.** {A12279}
11fd0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
11fe0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
11ff0 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
12000 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
12010 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 72 75  *          is ru
12020 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74  nning then bad t
12030 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c  hings will likel
12040 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69  y happen..*/.voi
12050 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  d sqlite3_interr
12060 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  upt(sqlite3*);..
12070 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
12080 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
12090 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73  SQL Statement Is
120a0 20 43 6f 6d 70 6c 65 74 65 20 7b 48 31 30 35 31   Complete {H1051
120b0 30 7d 20 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a 2a  0} <S70200>.**.*
120c0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
120d0 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
120e0 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70  command-line inp
120f0 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ut to determine 
12100 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  if the.** curren
12110 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74  tly entered text
12120 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63   seems to form c
12130 6f 6d 70 6c 65 74 65 20 61 20 53 51 4c 20 73 74  omplete a SQL st
12140 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66  atement or.** if
12150 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75   additional inpu
12160 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f  t is needed befo
12170 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74  re sending the t
12180 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69  ext into.** SQLi
12190 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20  te for parsing. 
121a0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
121b0 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74  return true if t
121c0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
121d0 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
121e0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
121f0 73 74 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 74  statement.  A st
12200 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65  atement is judge
12210 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c  d to be.** compl
12220 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77  ete if it ends w
12230 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20  ith a semicolon 
12240 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74  token and is not
12250 20 61 20 66 72 61 67 6d 65 6e 74 20 6f 66 20 61   a fragment of a
12260 0a 2a 2a 20 43 52 45 41 54 45 20 54 52 49 47 47  .** CREATE TRIGG
12270 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53  ER statement.  S
12280 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
12290 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
122a0 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
122b0 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
122c0 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
122d0 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
122e0 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
122f0 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
12300 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
12310 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
12320 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
12330 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
12340 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
12350 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
12360 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  nator..**.** The
12370 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
12380 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
12390 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
123a0 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
123b0 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
123c0 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
123d0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
123e0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 31  S:.**.** {H10511
123f0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 65  } A successful e
12400 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71  valuation of [sq
12410 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29  lite3_complete()
12420 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
12430 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
12440 74 65 31 36 28 29 5d 20 66 75 6e 63 74 69 6f 6e  te16()] function
12450 73 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  s shall.**      
12460 20 20 20 20 72 65 74 75 72 6e 20 61 20 6e 75 6d      return a num
12470 65 72 69 63 20 31 20 69 66 20 61 6e 64 20 6f 6e  eric 1 if and on
12480 6c 79 20 69 66 20 74 68 65 20 6c 61 73 74 20 6e  ly if the last n
12490 6f 6e 2d 77 68 69 74 65 73 70 61 63 65 0a 2a 2a  on-whitespace.**
124a0 20 20 20 20 20 20 20 20 20 20 74 6f 6b 65 6e 20            token 
124b0 69 6e 20 74 68 65 69 72 20 69 6e 70 75 74 20 69  in their input i
124c0 73 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68  s a semicolon th
124d0 61 74 20 69 73 20 6e 6f 74 20 69 6e 20 62 65 74  at is not in bet
124e0 77 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ween.**         
124f0 20 74 68 65 20 42 45 47 49 4e 20 61 6e 64 20 45   the BEGIN and E
12500 4e 44 20 6f 66 20 61 20 43 52 45 41 54 45 20 54  ND of a CREATE T
12510 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
12520 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 32 7d  ..**.** {H10512}
12530 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   If a memory all
12540 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
12550 63 75 72 73 20 64 75 72 69 6e 67 20 61 6e 20 69  curs during an i
12560 6e 76 6f 63 61 74 69 6f 6e 0a 2a 2a 20 20 20 20  nvocation.**    
12570 20 20 20 20 20 20 6f 66 20 5b 73 71 6c 69 74 65        of [sqlite
12580 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72  3_complete()] or
12590 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
125a0 74 65 31 36 28 29 5d 20 74 68 65 6e 20 74 68 65  te16()] then the
125b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75  .**          rou
125c0 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72  tine shall retur
125d0 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
125e0 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49  ..**.** ASSUMPTI
125f0 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35  ONS:.**.** {A105
12600 31 32 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f  12} The input to
12610 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
12620 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
12630 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
12640 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d  **          UTF-
12650 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
12660 7b 41 31 30 35 31 33 7d 20 54 68 65 20 69 6e 70  {A10513} The inp
12670 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
12680 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73  omplete16()] mus
12690 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
126a0 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  inated.**       
126b0 20 20 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67     UTF-16 string
126c0 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
126d0 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  order..*/.int sq
126e0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63  lite3_complete(c
126f0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b  onst char *sql);
12700 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
12710 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
12720 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
12730 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
12740 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
12750 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
12760 42 55 53 59 20 45 72 72 6f 72 73 20 7b 48 31 32  BUSY Errors {H12
12770 33 31 30 7d 20 3c 53 34 30 34 30 30 3e 0a 2a 2a  310} <S40400>.**
12780 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
12790 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b   sets a callback
127a0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d   function that m
127b0 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
127c0 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61  whenever.** an a
127d0 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
127e0 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73  o open a databas
127f0 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f  e table that ano
12800 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f  ther thread.** o
12810 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f  r process has lo
12820 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  cked..**.** If t
12830 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
12840 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
12850 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
12860 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
12870 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74  OCKED].** is ret
12880 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
12890 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
128a0 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 49 66  ing the lock. If
128b0 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
128c0 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c  ck.** is not NUL
128d0 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  L, then the call
128e0 62 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76  back will be inv
128f0 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72  oked with two ar
12900 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  guments..**.** T
12910 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
12920 74 20 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 72  t to the handler
12930 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
12940 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20  e void* pointer 
12950 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
12960 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
12970 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  o sqlite3_busy_h
12980 61 6e 64 6c 65 72 28 29 2e 20 20 54 68 65 20 73  andler().  The s
12990 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
129a0 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  o.** the handler
129b0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
129c0 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
129d0 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
129e0 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
129f0 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74  en invoked for t
12a00 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  his locking even
12a10 74 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 62 75  t.  If the.** bu
12a20 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
12a30 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
12a40 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
12a50 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
12a60 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
12a70 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
12a80 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
12a90 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
12aa0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
12ab0 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63  * If the callbac
12ac0 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
12ad0 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
12ae0 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d   attempt.** is m
12af0 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20  ade to open the 
12b00 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61  database for rea
12b10 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63  ding and the cyc
12b20 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
12b30 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
12b40 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
12b50 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
12b60 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c  tee that it will
12b70 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77   be invoked.** w
12b80 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
12b90 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49 66  k contention. If
12ba0 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e   SQLite determin
12bb0 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67  es that invoking
12bc0 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e   the busy.** han
12bd0 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c  dler could resul
12be0 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c  t in a deadlock,
12bf0 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61   it will go ahea
12c00 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  d and return [SQ
12c10 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72  LITE_BUSY].** or
12c20 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
12c30 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20  LOCKED] instead 
12c40 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  of invoking the 
12c50 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
12c60 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
12c70 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
12c80 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
12c90 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
12ca0 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
12cb0 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
12cc0 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
12cd0 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
12ce0 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
12cf0 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
12d00 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
12d10 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
12d20 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
12d30 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
12d40 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
12d50 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
12d60 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
12d70 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
12d80 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
12d90 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
12da0 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
12db0 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
12dc0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
12dd0 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
12de0 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
12df0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
12e00 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
12e10 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
12e20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
12e30 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
12e40 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
12e50 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
12e60 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
12e70 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
12e80 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
12e90 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
12ea0 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
12eb0 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
12ec0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
12ed0 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
12ee0 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
12ef0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
12f00 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  L..**.** The [SQ
12f10 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72  LITE_BUSY] error
12f20 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   is converted to
12f30 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
12f40 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20  LOCKED].** when 
12f50 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65  SQLite is in the
12f60 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72   middle of a lar
12f70 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77  ge transaction w
12f80 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20  here all the.** 
12f90 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74  changes will not
12fa0 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e   fit into the in
12fb0 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20  -memory cache.  
12fc0 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61  SQLite will.** a
12fd0 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45  lready hold a RE
12fe0 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74  SERVED lock on t
12ff0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
13000 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a  , but it needs.*
13010 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69  * to promote thi
13020 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53  s lock to EXCLUS
13030 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63  IVE so that it c
13040 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a  an spill cache.*
13050 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65  * pages into the
13060 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
13070 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63  ithout harm to c
13080 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61  oncurrent.** rea
13090 64 65 72 73 2e 20 20 49 66 20 69 74 20 69 73 20  ders.  If it is 
130a0 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74  unable to promot
130b0 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e  e the lock, then
130c0 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a   the in-memory.*
130d0 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20  * cache will be 
130e0 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e  left in an incon
130f0 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e  sistent state an
13100 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a  d so the error.*
13110 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74  * code is promot
13120 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61  ed from the rela
13130 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53  tively benign [S
13140 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a  QLITE_BUSY] to.*
13150 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72  * the more sever
13160 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  e [SQLITE_IOERR_
13170 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73 20  BLOCKED].  This 
13180 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f  error code promo
13190 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61  tion.** forces a
131a0 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c  n automatic roll
131b0 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e  back of the chan
131c0 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ges.  See the.**
131d0 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72   <a href="/cvstr
131e0 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70  ac/wiki?p=Corrup
131f0 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
13200 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72  yError">.** Corr
13210 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
13220 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b  usyError</a> wik
13230 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73  i page for a dis
13240 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a  cussion of why.*
13250 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74  * this is import
13260 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ant..**.** There
13270 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
13280 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
13290 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
132a0 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
132b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53   connection].  S
132c0 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
132d0 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
132e0 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73   any.** previous
132f0 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 20  ly set handler. 
13300 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69   Note that calli
13310 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
13320 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77  _timeout()].** w
13330 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20  ill also set or 
13340 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68  clear the busy h
13350 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  andler..**.** Th
13360 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
13370 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20  should not take 
13380 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63  any actions whic
13390 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20  h modify the.** 
133a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
133b0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
133c0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
133d0 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  r.  Any such act
133e0 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
133f0 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
13400 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 49 4e 56  vior..** .** INV
13410 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
13420 48 31 32 33 31 31 7d 20 54 68 65 20 5b 73 71 6c  H12311} The [sql
13430 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
13440 72 28 44 2c 43 2c 41 29 5d 20 66 75 6e 63 74 69  r(D,C,A)] functi
13450 6f 6e 20 73 68 61 6c 6c 20 72 65 70 6c 61 63 65  on shall replace
13460 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75 73  .**          bus
13470 79 20 63 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68  y callback in th
13480 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
13490 65 63 74 69 6f 6e 5d 20 44 20 77 69 74 68 20 61  ection] D with a
134a0 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20   new.**         
134b0 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
134c0 6c 65 72 20 43 20 61 6e 64 20 61 70 70 6c 69 63  ler C and applic
134d0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
134e0 65 72 20 41 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  er A..**.** {H12
134f0 33 31 32 7d 20 4e 65 77 6c 79 20 63 72 65 61 74  312} Newly creat
13500 65 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ed [database con
13510 6e 65 63 74 69 6f 6e 73 5d 20 73 68 61 6c 6c 20  nections] shall 
13520 68 61 76 65 20 61 20 62 75 73 79 0a 2a 2a 20 20  have a busy.**  
13530 20 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20          handler 
13540 6f 66 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b  of NULL..**.** {
13550 48 31 32 33 31 34 7d 20 57 68 65 6e 20 74 77 6f  H12314} When two
13560 20 6f 72 20 6d 6f 72 65 20 5b 64 61 74 61 62 61   or more [databa
13570 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
13580 73 68 61 72 65 20 61 0a 2a 2a 20 20 20 20 20 20  share a.**      
13590 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61      [sqlite3_ena
135a0 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
135b0 20 7c 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 5d   | common cache]
135c0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
135d0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
135e0 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
135f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 65  connection curre
13600 6e 74 6c 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ntly using.**   
13610 20 20 20 20 20 20 20 74 68 65 20 63 61 63 68 65         the cache
13620 20 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65   shall be invoke
13630 64 20 77 68 65 6e 20 74 68 65 20 63 61 63 68 65  d when the cache
13640 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 6c 6f   encounters a lo
13650 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31  ck..**.** {H1231
13660 36 7d 20 49 66 20 61 20 62 75 73 79 20 68 61 6e  6} If a busy han
13670 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  dler callback re
13680 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e  turns zero, then
13690 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
136a0 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20  rface.**        
136b0 20 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20    that provoked 
136c0 74 68 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  the locking even
136d0 74 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b  t shall return [
136e0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
136f0 0a 2a 2a 20 7b 48 31 32 33 31 38 7d 20 53 51 4c  .** {H12318} SQL
13700 69 74 65 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65  ite shall invoke
13710 73 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  s the busy handl
13720 65 72 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  er with two argu
13730 6d 65 6e 74 73 20 77 68 69 63 68 0a 2a 2a 20 20  ments which.**  
13740 20 20 20 20 20 20 20 20 61 72 65 20 61 20 63 6f          are a co
13750 70 79 20 6f 66 20 74 68 65 20 70 6f 69 6e 74 65  py of the pointe
13760 72 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68  r supplied by th
13770 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
13780 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
13790 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
137a0 64 6c 65 72 28 29 5d 20 61 6e 64 20 61 20 63 6f  dler()] and a co
137b0 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  unt of the numbe
137c0 72 20 6f 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20  r of prior.**   
137d0 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f         invocatio
137e0 6e 73 20 6f 66 20 74 68 65 20 62 75 73 79 20 68  ns of the busy h
137f0 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 73  andler for the s
13800 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  ame locking even
13810 74 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54  t..**.** ASSUMPT
13820 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  IONS:.**.** {A12
13830 33 31 39 7d 20 41 20 62 75 73 79 20 68 61 6e 64  319} A busy hand
13840 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
13850 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
13860 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20  connection.**   
13870 20 20 20 20 20 20 20 6f 72 20 5b 70 72 65 70 61         or [prepa
13880 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
13890 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
138a0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f  busy handler..*/
138b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
138c0 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  y_handler(sqlite
138d0 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
138e0 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  ,int), void*);..
138f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13900 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
13910 75 74 20 7b 48 31 32 33 34 30 7d 20 3c 53 34 30  ut {H12340} <S40
13920 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  410>.**.** This 
13930 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b  routine sets a [
13940 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
13950 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64  dler | busy hand
13960 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73  ler] that sleeps
13970 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66  .** for a specif
13980 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69  ied amount of ti
13990 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20  me when a table 
139a0 69 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20  is locked.  The 
139b0 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20  handler.** will 
139c0 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
139d0 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65  imes until at le
139e0 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
139f0 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
13a00 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75  g.** have accumu
13a10 6c 61 74 65 64 2e 20 7b 48 31 32 33 34 33 7d 20  lated. {H12343} 
13a20 41 66 74 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69  After "ms" milli
13a30 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
13a40 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
13a50 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
13a60 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
13a70 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
13a80 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
13a90 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
13aa0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
13ab0 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20  ..**.** Calling 
13ac0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
13ad0 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65  h an argument le
13ae0 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
13af0 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e   to zero.** turn
13b00 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68  s off all busy h
13b10 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54  andlers..**.** T
13b20 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
13b30 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
13b40 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72  andler for a par
13b50 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
13b60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
13b70 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d   any any given m
13b80 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68  oment.  If anoth
13b90 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a  er busy handler.
13ba0 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20  ** was defined  
13bb0 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  (using [sqlite3_
13bc0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29  busy_handler()])
13bd0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
13be0 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  g.** this routin
13bf0 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75  e, that other bu
13c00 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c  sy handler is cl
13c10 65 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  eared..**.** INV
13c20 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
13c30 48 31 32 33 34 31 7d 20 54 68 65 20 5b 73 71 6c  H12341} The [sql
13c40 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
13c50 74 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68  t()] function sh
13c60 61 6c 6c 20 6f 76 65 72 72 69 64 65 20 61 6e 79  all override any
13c70 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20   prior.**       
13c80 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79     [sqlite3_busy
13c90 5f 74 69 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b  _timeout()] or [
13ca0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
13cb0 64 6c 65 72 28 29 5d 20 73 65 74 74 69 6e 67 0a  dler()] setting.
13cc0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74  **          on t
13cd0 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
13ce0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
13cf0 2a 0a 2a 2a 20 7b 48 31 32 33 34 33 7d 20 49 66  *.** {H12343} If
13d00 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
13d10 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
13d20 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69  usy_timeout()] i
13d30 73 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20  s less than.**  
13d40 20 20 20 20 20 20 20 20 6f 72 20 65 71 75 61 6c          or equal
13d50 20 74 6f 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74   to zero, then t
13d60 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
13d70 73 68 61 6c 6c 20 62 65 20 63 6c 65 61 72 65 64  shall be cleared
13d80 20 73 6f 20 74 68 61 74 0a 2a 2a 20 20 20 20 20   so that.**     
13d90 20 20 20 20 20 61 6c 6c 20 73 75 62 73 65 71 75       all subsequ
13da0 65 6e 74 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  ent locking even
13db0 74 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 72  ts immediately r
13dc0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
13dd0 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  SY]..**.** {H123
13de0 34 34 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70  44} If the 2nd p
13df0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
13e00 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
13e10 74 28 29 5d 20 69 73 20 61 20 70 6f 73 69 74 69  t()] is a positi
13e20 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  ve.**          n
13e30 75 6d 62 65 72 20 4e 2c 20 74 68 65 6e 20 61 20  umber N, then a 
13e40 62 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68 61  busy handler sha
13e50 6c 6c 20 62 65 20 73 65 74 20 74 68 61 74 20 72  ll be set that r
13e60 65 70 65 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a  epeatedly calls.
13e70 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
13e80 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
13e90 69 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  in the [sqlite3_
13ea0 76 66 73 20 7c 20 56 46 53 20 69 6e 74 65 72 66  vfs | VFS interf
13eb0 61 63 65 5d 20 75 6e 74 69 6c 0a 2a 2a 20 20 20  ace] until.**   
13ec0 20 20 20 20 20 20 20 65 69 74 68 65 72 20 74 68         either th
13ed0 65 20 6c 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72  e lock clears or
13ee0 20 75 6e 74 69 6c 20 74 68 65 20 63 75 6d 75 6c   until the cumul
13ef0 61 74 69 76 65 20 73 6c 65 65 70 20 74 69 6d 65  ative sleep time
13f00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 70  .**          rep
13f10 6f 72 74 65 64 20 62 61 63 6b 20 62 79 20 78 53  orted back by xS
13f20 6c 65 65 70 28 29 20 65 78 63 65 65 64 73 20 4e  leep() exceeds N
13f30 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a   milliseconds..*
13f40 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
13f50 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
13f60 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
13f70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
13f80 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
13f90 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
13fa0 51 75 65 72 69 65 73 20 7b 48 31 32 33 37 30 7d  Queries {H12370}
13fb0 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10000>.**.** 
13fc0 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62  Definition: A <b
13fd0 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62  >result table</b
13fe0 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61  > is memory data
13ff0 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74   structure creat
14000 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71  ed by the.** [sq
14010 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
14020 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41  )] interface.  A
14030 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65   result table re
14040 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d  cords the.** com
14050 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75  plete query resu
14060 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20  lts from one or 
14070 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a  more queries..**
14080 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f  .** The table co
14090 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61  nceptually has a
140a0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
140b0 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75  and columns.  Bu
140c0 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65  t.** these numbe
140d0 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20  rs are not part 
140e0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
140f0 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65  ble itself.  The
14100 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72  se.** numbers ar
14110 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72  e obtained separ
14120 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65  ately.  Let N be
14130 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
14140 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20  ows.** and M be 
14150 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
14160 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  lumns..**.** A r
14170 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61  esult table is a
14180 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
14190 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  ers to zero-term
141a0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
141b0 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61  ings..** There a
141c0 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65  re (N+1)*M eleme
141d0 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79  nts in the array
141e0 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70  .  The first M p
141f0 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a  ointers point.**
14200 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
14210 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
14220 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61    contain the na
14230 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  mes of the colum
14240 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  ns..** The remai
14250 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c  ning entries all
14260 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20   point to query 
14270 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76  results.  NULL v
14280 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20  alues result.** 
14290 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  in NULL pointers
142a0 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  .  All other val
142b0 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72  ues are in their
142c0 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
142d0 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
142e0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
142f0 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  as returned by [
14300 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
14310 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20  ext()]..**.** A 
14320 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67  result table mig
14330 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e  ht consist of on
14340 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79  e or more memory
14350 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a   allocations..**
14360 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
14370 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74  to pass a result
14380 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20   table directly 
14390 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
143a0 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ()]..** A result
143b0 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65   table should be
143c0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69   deallocated usi
143d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
143e0 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _table()]..**.**
143f0 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   As an example o
14400 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
14410 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
14420 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
14430 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
14440 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
14450 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
14460 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
14470 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
14480 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
14490 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
144a0 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
144b0 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
144c0 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
144d0 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
144e0 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
144f0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
14500 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
14510 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
14520 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
14530 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
14540 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
14550 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
14560 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
14570 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
14580 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
14590 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
145a0 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
145b0 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
145c0 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
145d0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
145e0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
145f0 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
14600 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
14610 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
14620 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
14630 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
14640 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
14650 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
14660 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
14670 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
14680 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
14690 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
146a0 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
146b0 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
146c0 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
146d0 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
146e0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
146f0 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
14700 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
14710 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e>.**.** The sql
14720 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
14730 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
14740 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
14750 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
14760 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
14770 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
14780 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
14790 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
147a0 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
147b0 72 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 61  r.  It returns a
147c0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
147d0 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
147e0 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
147f0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
14800 2a 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c  * After the call
14810 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73  ing function has
14820 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
14830 74 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73  the result, it s
14840 68 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68  hould.** pass th
14850 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
14860 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
14870 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
14880 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
14890 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
148a0 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
148b0 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
148c0 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
148d0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
148e0 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
148f0 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
14900 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
14910 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
14920 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
14930 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
14940 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
14950 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
14960 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
14970 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
14980 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
14990 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
149a0 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
149b0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
149c0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
149d0 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
149e0 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
149f0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
14a00 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
14a10 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
14a20 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
14a30 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
14a40 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
14a50 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
14a60 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
14a70 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
14a80 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
14a90 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
14aa0 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
14ab0 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
14ac0 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
14ad0 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
14ae0 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
14af0 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
14b00 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
14b10 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
14b20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
14b30 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
14b40 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73  errcode()] or [s
14b50 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
14b60 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
14b70 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37  TS:.**.** {H1237
14b80 31 7d 20 49 66 20 61 20 5b 73 71 6c 69 74 65 33  1} If a [sqlite3
14b90 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 61  _get_table()] fa
14ba0 69 6c 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  ils a memory all
14bb0 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a  ocation, then.**
14bc0 20 20 20 20 20 20 20 20 20 20 69 74 20 73 68 61            it sha
14bd0 6c 6c 20 66 72 65 65 20 74 68 65 20 72 65 73 75  ll free the resu
14be0 6c 74 20 74 61 62 6c 65 20 75 6e 64 65 72 20 63  lt table under c
14bf0 6f 6e 73 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f  onstruction, abo
14c00 72 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  rt the.**       
14c10 20 20 20 71 75 65 72 79 20 69 6e 20 70 72 6f 63     query in proc
14c20 65 73 73 2c 20 73 6b 69 70 20 61 6e 79 20 73 75  ess, skip any su
14c30 62 73 65 71 75 65 6e 74 20 71 75 65 72 69 65 73  bsequent queries
14c40 2c 20 73 65 74 20 74 68 65 0a 2a 2a 20 20 20 20  , set the.**    
14c50 20 20 20 20 20 20 2a 70 61 7a 52 65 73 75 6c 74        *pazResult
14c60 20 6f 75 74 70 75 74 20 70 6f 69 6e 74 65 72 20   output pointer 
14c70 74 6f 20 4e 55 4c 4c 20 61 6e 64 20 72 65 74 75  to NULL and retu
14c80 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  rn [SQLITE_NOMEM
14c90 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 33  ]..**.** {H12373
14ca0 7d 20 49 66 20 74 68 65 20 70 6e 43 6f 6c 75 6d  } If the pnColum
14cb0 6e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  n parameter to [
14cc0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
14cd0 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  e()] is not NULL
14ce0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
14cf0 6e 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 69  n a successful i
14d00 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
14d10 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
14d20 29 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20  )] shall.**     
14d30 20 20 20 20 20 77 72 69 74 65 20 74 68 65 20 6e       write the n
14d40 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
14d50 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   in the.**      
14d60 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f      result set o
14d70 66 20 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f  f the query into
14d80 20 2a 70 6e 43 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a   *pnColumn..**.*
14d90 2a 20 7b 48 31 32 33 37 34 7d 20 49 66 20 74 68  * {H12374} If th
14da0 65 20 70 6e 52 6f 77 20 70 61 72 61 6d 65 74 65  e pnRow paramete
14db0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65  r to [sqlite3_ge
14dc0 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f  t_table()] is no
14dd0 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20  t NULL.**       
14de0 20 20 20 74 68 65 6e 20 61 20 73 75 63 63 65 73     then a succes
14df0 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
14e00 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  of [sqlite3_get_
14e10 74 61 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a  table()] shall.*
14e20 2a 20 20 20 20 20 20 20 20 20 20 77 72 69 74 65  *          write
14e30 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
14e40 72 6f 77 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20  rows in the.**  
14e50 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73          result s
14e60 65 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  et of the query 
14e70 69 6e 74 6f 20 2a 70 6e 52 6f 77 2e 0a 2a 2a 0a  into *pnRow..**.
14e80 2a 2a 20 7b 48 31 32 33 37 36 7d 20 41 20 73 75  ** {H12376} A su
14e90 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
14ea0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
14eb0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 74 68 61  get_table()] tha
14ec0 74 20 63 6f 6d 70 75 74 65 73 0a 2a 2a 20 20 20  t computes.**   
14ed0 20 20 20 20 20 20 20 4e 20 72 6f 77 73 20 6f 66         N rows of
14ee0 20 72 65 73 75 6c 74 20 77 69 74 68 20 43 20 63   result with C c
14ef0 6f 6c 75 6d 6e 73 20 70 65 72 20 72 6f 77 20 73  olumns per row s
14f00 68 61 6c 6c 20 6d 61 6b 65 20 2a 70 61 7a 52 65  hall make *pazRe
14f10 73 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  sult.**         
14f20 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 72 72   point to an arr
14f30 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
14f40 6f 20 28 4e 2b 31 29 2a 43 20 73 74 72 69 6e 67  o (N+1)*C string
14f50 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73  s where the firs
14f60 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 20  t.**          C 
14f70 73 74 72 69 6e 67 73 20 61 72 65 20 63 6f 6c 75  strings are colu
14f80 6d 6e 20 6e 61 6d 65 73 20 61 73 20 6f 62 74 61  mn names as obta
14f90 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 20 20 20  ined from.**    
14fa0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
14fb0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e  olumn_name()] an
14fc0 64 20 74 68 65 20 72 65 73 74 20 61 72 65 20 63  d the rest are c
14fd0 6f 6c 75 6d 6e 20 72 65 73 75 6c 74 20 76 61 6c  olumn result val
14fe0 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ues.**          
14ff0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
15000 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
15010 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  xt()]..**.** {H1
15020 32 33 37 39 7d 20 54 68 65 20 76 61 6c 75 65 73  2379} The values
15030 20 69 6e 20 74 68 65 20 70 61 7a 52 65 73 75 6c   in the pazResul
15040 74 20 61 72 72 61 79 20 72 65 74 75 72 6e 65 64  t array returned
15050 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 67 65 74   by [sqlite3_get
15060 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20  _table()].**    
15070 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65 6d 61        shall rema
15080 69 6e 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 63  in valid until c
15090 6c 65 61 72 65 64 20 62 79 20 5b 73 71 6c 69 74  leared by [sqlit
150a0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
150b0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 38 32 7d  ..**.** {H12382}
150c0 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f   When an error o
150d0 63 63 75 72 73 20 64 75 72 69 6e 67 20 65 76 61  ccurs during eva
150e0 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  luation of [sqli
150f0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
15100 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
15110 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
15120 73 65 74 20 2a 70 61 7a 52 65 73 75 6c 74 20 74  set *pazResult t
15130 6f 20 4e 55 4c 4c 2c 20 77 72 69 74 65 20 61 6e  o NULL, write an
15140 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
15150 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 6f 20  *          into 
15160 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
15170 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
15180 6c 6c 6f 63 28 29 5d 2c 20 6d 61 6b 65 0a 2a 2a  lloc()], make.**
15190 20 20 20 20 20 20 20 20 20 20 2a 2a 70 7a 45 72            **pzEr
151a0 72 6d 73 67 20 70 6f 69 6e 74 20 74 6f 20 74 68  rmsg point to th
151b0 61 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  at error message
151c0 2c 20 61 6e 64 20 72 65 74 75 72 6e 20 61 0a 2a  , and return a.*
151d0 2a 20 20 20 20 20 20 20 20 20 20 61 70 70 72 6f  *          appro
151e0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
151f0 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  de]..*/.int sqli
15200 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
15210 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
15220 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
15230 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
15240 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
15250 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
15260 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
15270 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
15280 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
15290 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
152a0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
152b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
152c0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
152d0 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
152e0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
152f0 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
15300 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
15310 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
15320 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
15330 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
15340 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
15350 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
15360 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
15370 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
15380 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
15390 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
153a0 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
153b0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31  ng Functions {H1
153c0 37 34 30 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53  7400} <S70000><S
153d0 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20000>.**.** The
153e0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
153f0 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68  workalikes of th
15400 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d  e "printf()" fam
15410 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
15420 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61  .** from the sta
15430 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
15440 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
15450 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
15460 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
15470 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
15480 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
15490 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
154a0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
154b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
154c0 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
154d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
154e0 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
154f0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
15500 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
15510 33 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68  3_free()].  Both
15520 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
15530 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
15540 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
15550 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
15560 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
15570 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
15580 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
15590 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
155a0 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73  .** In sqlite3_s
155b0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
155c0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
155d0 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
155e0 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
155f0 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
15600 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
15610 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
15620 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
15630 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
15640 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
15650 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
15660 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
15670 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74  meter. Note that
15680 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   the order of th
15690 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70  e.** first two p
156a0 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76  arameters is rev
156b0 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69  ersed from snpri
156c0 6e 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 20  ntf().  This is 
156d0 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
156e0 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
156f0 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
15700 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
15710 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
15720 70 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74  patibility.  Not
15730 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69  e also that sqli
15740 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
15750 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
15760 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65  ter to its buffe
15770 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
15780 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
15790 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c  aracters actuall
157a0 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  y written into t
157b0 68 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 61  he buffer.  We a
157c0 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
157d0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
157e0 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
157f0 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
15800 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
15810 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
15820 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
15830 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
15840 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
15850 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
15860 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
15870 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
15880 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62  As long as the b
15890 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72  uffer size is gr
158a0 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c  eater than zero,
158b0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
158c0 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  f().** guarantee
158d0 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65  s that the buffe
158e0 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  r is always zero
158f0 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68  -terminated.  Th
15900 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
15910 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
15920 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
15930 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
15940 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
15950 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
15960 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
15970 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
15980 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
15990 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
159a0 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
159b0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  cters..**.** The
159c0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20  se routines all 
159d0 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61  implement some a
159e0 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74  dditional format
159f0 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20  ting.** options 
15a00 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
15a10 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67  for constructing
15a20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
15a30 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75  .** All of the u
15a40 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f  sual printf() fo
15a50 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
15a60 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69   apply.  In addi
15a70 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69  tion, there.** i
15a80 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22  s are "%q", "%Q"
15a90 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f  , and "%z" optio
15aa0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71  ns..**.** The %q
15ab0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
15ac0 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
15ad0 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
15ae0 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ull-terminated.*
15af0 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68  * string from th
15b00 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e  e argument list.
15b10 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f    But %q also do
15b20 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27  ubles every '\''
15b30 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25   character..** %
15b40 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  q is designed fo
15b50 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73  r use inside a s
15b60 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20  tring literal.  
15b70 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
15b80 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
15b90 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
15ba0 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
15bb0 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
15bc0 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
15bd0 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
15be0 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
15bf0 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69   assume the stri
15c00 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78  ng variable zTex
15c10 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  t contains text 
15c20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
15c30 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
15c40 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
15c50 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
15c60 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
15c70 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
15c80 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
15c90 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
15ca0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
15cb0 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
15cc0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
15cd0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
15ce0 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
15cf0 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
15d00 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
15d10 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
15d20 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
15d30 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
15d40 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
15d50 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
15d60 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
15d70 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
15d80 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
15d90 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
15da0 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
15db0 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
15dc0 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
15dd0 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
15de0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
15df0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
15e00 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
15e10 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
15e20 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
15e30 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
15e40 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
15e50 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
15e60 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
15e70 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
15e80 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
15e90 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
15ea0 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
15eb0 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
15ec0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
15ed0 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
15ee0 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
15ef0 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
15f00 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
15f10 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
15f20 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
15f30 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
15f40 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
15f50 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
15f60 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a  le you should.**
15f70 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
15f80 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
15f90 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
15fa0 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c   into a string l
15fb0 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  iteral..**.** Th
15fc0 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %Q option work
15fd0 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74  s like %q except
15fe0 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69   it also adds si
15ff0 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75  ngle quotes arou
16000 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64  nd.** the outsid
16010 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73  e of the total s
16020 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  tring.  Addition
16030 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72  ally, if the par
16040 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a  ameter in the.**
16050 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69   argument list i
16060 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
16070 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73  , %Q substitutes
16080 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22   the text "NULL"
16090 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e   (without.** sin
160a0 67 6c 65 20 71 75 6f 74 65 73 29 20 69 6e 20 70  gle quotes) in p
160b0 6c 61 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f  lace of the %Q o
160c0 70 74 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20  ption.  So, for 
160d0 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
160e0 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
160f0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
16100 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
16110 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
16120 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
16130 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
16140 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
16150 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
16160 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
16170 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
16180 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
16190 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
161a0 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
161b0 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
161c0 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
161d0 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
161e0 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
161f0 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
16200 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
16210 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
16220 2a 20 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61  * The "%z" forma
16230 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72  tting option wor
16240 6b 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20  ks exactly like 
16250 22 25 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a  "%s" with the.**
16260 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
16270 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
16280 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
16290 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
162a0 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
162b0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
162c0 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
162d0 6e 70 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e  nput string. {EN
162e0 44 7d 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  D}.**.** INVARIA
162f0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34  NTS:.**.** {H174
16300 30 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  03}  The [sqlite
16310 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 61 6e 64  3_mprintf()] and
16320 20 5b 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   [sqlite3_vmprin
16330 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  tf()] interfaces
16340 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
16350 74 75 72 6e 20 65 69 74 68 65 72 20 70 6f 69 6e  turn either poin
16360 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
16370 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
16380 72 69 6e 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a  rings held in.**
16390 20 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72             memor
163a0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
163b0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
163c0 29 5d 20 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74  )] or NULL point
163d0 65 72 73 20 69 66 0a 2a 2a 20 20 20 20 20 20 20  ers if.**       
163e0 20 20 20 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73      a call to [s
163f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
16400 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48   fails..**.** {H
16410 31 37 34 30 36 7d 20 20 54 68 65 20 5b 73 71 6c  17406}  The [sql
16420 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
16430 20 69 6e 74 65 72 66 61 63 65 20 77 72 69 74 65   interface write
16440 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
16450 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
16460 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e   UTF-8 string in
16470 74 6f 20 74 68 65 20 62 75 66 66 65 72 20 70 6f  to the buffer po
16480 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
16490 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
164a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 70 72  .**           pr
164b0 6f 76 69 64 65 64 20 74 68 61 74 20 74 68 65 20  ovided that the 
164c0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
164d0 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
164e0 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  zero..**.** {H17
164f0 34 30 37 7d 20 20 54 68 65 20 5b 73 71 6c 69 74  407}  The [sqlit
16500 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
16510 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
16520 74 20 77 72 69 74 65 20 73 6c 6f 74 73 20 6f 66  t write slots of
16530 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74  .**           it
16540 73 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  s output buffer 
16550 28 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  (the second para
16560 6d 65 74 65 72 29 20 6f 75 74 73 69 64 65 20 74  meter) outside t
16570 68 65 20 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20  he range.**     
16580 20 20 20 20 20 20 6f 66 20 30 20 74 68 72 6f 75        of 0 throu
16590 67 68 20 4e 2d 31 20 28 77 68 65 72 65 20 4e 20  gh N-1 (where N 
165a0 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
165b0 61 6d 65 74 65 72 29 0a 2a 2a 20 20 20 20 20 20  ameter).**      
165c0 20 20 20 20 20 72 65 67 61 72 64 6c 65 73 73 20       regardless 
165d0 6f 66 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  of the length of
165e0 20 74 68 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20   the string.**  
165f0 20 20 20 20 20 20 20 20 20 72 65 71 75 65 73 74           request
16600 65 64 20 62 79 20 74 68 65 20 66 6f 72 6d 61 74  ed by the format
16610 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a   specification..
16620 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  */.char *sqlite3
16630 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
16640 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20  har*,...);.char 
16650 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
16660 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
16670 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73  a_list);.char *s
16680 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
16690 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
166a0 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  char*, ...);../*
166b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
166c0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
166d0 53 75 62 73 79 73 74 65 6d 20 7b 48 31 37 33 30  Subsystem {H1730
166e0 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a  0} <S20000>.**.*
166f0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
16700 65 20 20 75 73 65 73 20 74 68 65 73 65 20 74 68  e  uses these th
16710 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
16720 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
16730 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
16740 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
16750 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74  eds. "Core" in t
16760 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
16770 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ence.** does not
16780 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69   include operati
16790 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
167a0 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ic VFS implement
167b0 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57  ation.  The.** W
167c0 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20  indows VFS uses 
167d0 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20  native malloc() 
167e0 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73  and free() for s
167f0 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  ome operations..
16800 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
16810 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
16820 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
16830 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
16840 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
16850 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
16860 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
16870 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
16880 72 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33  r..** If sqlite3
16890 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
168a0 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
168b0 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
168c0 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
168d0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
168e0 65 72 2e 20 20 49 66 20 74 68 65 20 70 61 72 61  er.  If the para
168f0 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71  meter N to.** sq
16900 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
16910 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69  s zero or negati
16920 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ve then sqlite3_
16930 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  malloc() returns
16940 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
16950 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e  er..**.** Callin
16960 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
16970 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
16980 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
16990 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
169a0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
169b0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
169c0 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
169d0 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
169e0 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
169f0 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ed.  The sqlite3
16a00 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
16a10 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
16a20 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
16a30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
16a40 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
16a50 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
16a60 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
16a70 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
16a80 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
16a90 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
16aa0 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
16ab0 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
16ac0 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
16ad0 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
16ae0 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
16af0 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
16b00 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
16b10 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
16b20 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
16b30 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
16b40 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
16b50 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
16b60 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
16b70 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
16b80 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
16b90 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
16ba0 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
16bb0 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
16bc0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
16bd0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
16be0 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
16bf0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
16c00 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63  alloc() interfac
16c10 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
16c20 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
16c30 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
16c40 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  n to be at least
16c50 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20   N bytes, where 
16c60 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f  N is the.** seco
16c70 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
16c80 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
16c90 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a  tion to be resiz
16ca0 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  ed is the first.
16cb0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  ** parameter.  I
16cc0 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
16cd0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
16ce0 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
16cf0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
16d00 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
16d10 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
16d20 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
16d30 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77  ite3_malloc(N) w
16d40 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
16d50 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
16d60 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
16d70 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73  c()..** If the s
16d80 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
16d90 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
16da0 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  oc() is zero or.
16db0 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
16dc0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
16dd0 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
16de0 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
16df0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20  sqlite3_free(P) 
16e00 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66  where P is the f
16e10 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
16e20 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
16e30 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  c()..** sqlite3_
16e40 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
16e50 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
16e60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
16e70 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
16e80 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
16e90 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66  e or NULL if suf
16ea0 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
16eb0 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
16ec0 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20 73 69  * If M is the si
16ed0 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
16ee0 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
16ef0 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
16f00 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
16f10 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
16f20 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
16f30 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
16f40 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
16f50 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
16f60 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  c() and the prio
16f70 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
16f80 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c  freed..** If sql
16f90 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
16fa0 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
16fb0 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  n the prior allo
16fc0 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74  cation.** is not
16fd0 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68   freed..**.** Th
16fe0 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
16ff0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
17000 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65  loc() and sqlite
17010 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
17020 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
17030 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
17040 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8 byte boundary.
17050 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
17060 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65   default impleme
17070 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 6d  ntation of the m
17080 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
17090 20 73 75 62 73 79 73 74 65 6d 20 75 73 65 73 0a   subsystem uses.
170a0 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c  ** the malloc(),
170b0 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66   realloc() and f
170c0 72 65 65 28 29 20 70 72 6f 76 69 64 65 64 20 62  ree() provided b
170d0 79 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  y the standard C
170e0 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b 48 31   library..** {H1
170f0 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20 69  7382} However, i
17100 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
17110 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
17120 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53   SQLITE_MEMORY_S
17130 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43  IZE=<i>NNN</i> C
17140 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
17150 63 72 6f 20 28 77 68 65 72 65 20 3c 69 3e 4e 4e  cro (where <i>NN
17160 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e 20 69  N</i>.** is an i
17170 6e 74 65 67 65 72 29 2c 20 74 68 65 6e 20 53 51  nteger), then SQ
17180 4c 69 74 65 20 63 72 65 61 74 65 20 61 20 73 74  Lite create a st
17190 61 74 69 63 20 61 72 72 61 79 20 6f 66 20 61 74  atic array of at
171a0 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e   least.** <i>NNN
171b0 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73 69  </i> bytes in si
171c0 7a 65 20 61 6e 64 20 75 73 65 73 20 74 68 61 74  ze and uses that
171d0 20 61 72 72 61 79 20 66 6f 72 20 61 6c 6c 20 6f   array for all o
171e0 66 20 69 74 73 20 64 79 6e 61 6d 69 63 0a 2a 2a  f its dynamic.**
171f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
17200 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20  on needs. {END} 
17210 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f   Additional memo
17220 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74  ry allocator opt
17230 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61  ions.** may be a
17240 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
17250 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49  eleases..**.** I
17260 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
17270 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31   3.5.0 and 3.5.1
17280 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c  , it was possibl
17290 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74  e to define.** t
172a0 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  he SQLITE_OMIT_M
172b0 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
172c0 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75   which would cau
172d0 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  se the built-in.
172e0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
172f0 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  n of these routi
17300 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65  nes to be omitte
17310 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c  d.  That capabil
17320 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e  ity.** is no lon
17330 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f  ger provided.  O
17340 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  nly built-in mem
17350 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63  ory allocators c
17360 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a  an be used..**.*
17370 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53  * The Windows OS
17380 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
17390 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79   calls.** the sy
173a0 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  stem malloc() an
173b0 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c  d free() directl
173c0 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e  y when convertin
173d0 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62  g.** filenames b
173e0 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38  etween the UTF-8
173f0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62   encoding used b
17400 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
17410 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d  whatever filenam
17420 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  e encoding is us
17430 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63  ed by the partic
17440 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20  ular Windows.** 
17450 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d  installation.  M
17460 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
17470 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65   errors are dete
17480 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65  cted, but.** the
17490 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62  y are reported b
174a0 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
174b0 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
174c0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
174d0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
174e0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
174f0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
17500 2a 20 7b 48 31 37 33 30 33 7d 20 20 54 68 65 20  * {H17303}  The 
17510 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
17520 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
17530 74 75 72 6e 73 20 65 69 74 68 65 72 20 61 20 70  turns either a p
17540 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20  ointer to.**    
17550 20 20 20 20 20 20 20 61 20 6e 65 77 6c 79 20 63         a newly c
17560 68 65 63 6b 65 64 2d 6f 75 74 20 62 6c 6f 63 6b  hecked-out block
17570 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
17580 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ytes of memory.*
17590 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61 74  *           that
175a0 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   is 8-byte align
175b0 65 64 2c 20 6f 72 20 69 74 20 72 65 74 75 72 6e  ed, or it return
175c0 73 20 4e 55 4c 4c 20 69 66 20 69 74 20 69 73 20  s NULL if it is 
175d0 75 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20  unable.**       
175e0 20 20 20 20 74 6f 20 66 75 6c 66 69 6c 6c 20 74      to fulfill t
175f0 68 65 20 72 65 71 75 65 73 74 2e 0a 2a 2a 0a 2a  he request..**.*
17600 2a 20 7b 48 31 37 33 30 34 7d 20 20 54 68 65 20  * {H17304}  The 
17610 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
17620 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
17630 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
17640 6e 74 65 72 20 69 66 0a 2a 2a 20 20 20 20 20 20  nter if.**      
17650 20 20 20 20 20 4e 20 69 73 20 6c 65 73 73 20 74       N is less t
17660 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
17670 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  zero..**.** {H17
17680 33 30 35 7d 20 20 54 68 65 20 5b 73 71 6c 69 74  305}  The [sqlit
17690 65 33 5f 66 72 65 65 28 50 29 5d 20 69 6e 74 65  e3_free(P)] inte
176a0 72 66 61 63 65 20 72 65 6c 65 61 73 65 73 20 6d  rface releases m
176b0 65 6d 6f 72 79 20 70 72 65 76 69 6f 75 73 6c 79  emory previously
176c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
176d0 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
176e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
176f0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
17700 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  oc()],.**       
17710 20 20 20 20 6d 61 6b 69 6e 67 20 69 74 20 61 76      making it av
17720 61 69 6c 61 62 6c 65 20 66 6f 72 20 72 65 75 73  ailable for reus
17730 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 36  e..**.** {H17306
17740 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71  }  A call to [sq
17750 6c 69 74 65 33 5f 66 72 65 65 28 4e 55 4c 4c 29  lite3_free(NULL)
17760 5d 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  ] is a harmless 
17770 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  no-op..**.** {H1
17780 37 33 31 30 7d 20 20 41 20 63 61 6c 6c 20 74 6f  7310}  A call to
17790 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
177a0 63 28 30 2c 4e 29 5d 20 69 73 20 65 71 75 69 76  c(0,N)] is equiv
177b0 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a  alent to a call.
177c0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20  **           to 
177d0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
177e0 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  N)]..**.** {H173
177f0 31 32 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b  12}  A call to [
17800 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
17810 50 2c 30 29 5d 20 69 73 20 65 71 75 69 76 61 6c  P,0)] is equival
17820 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a  ent to a call.**
17830 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73             to [s
17840 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d 2e  qlite3_free(P)].
17850 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 35 7d 20  .**.** {H17315} 
17860 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
17870 20 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d   uses [sqlite3_m
17880 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
17890 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  e3_realloc()],.*
178a0 2a 20 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  *           and 
178b0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
178c0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
178d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
178e0 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  n and.**        
178f0 20 20 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 20     deallocation 
17900 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  needs..**.** {H1
17910 37 33 31 38 7d 20 20 54 68 65 20 5b 73 71 6c 69  7318}  The [sqli
17920 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29  te3_realloc(P,N)
17930 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
17940 72 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f 69  rns either a poi
17950 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  nter.**         
17960 20 20 74 6f 20 61 20 62 6c 6f 63 6b 20 6f 66 20    to a block of 
17970 63 68 65 63 6b 65 64 2d 6f 75 74 20 6d 65 6d 6f  checked-out memo
17980 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ry of at least N
17990 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 0a 2a   bytes in size.*
179a0 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61 74  *           that
179b0 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   is 8-byte align
179c0 65 64 2c 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  ed, or a NULL po
179d0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  inter..**.** {H1
179e0 37 33 32 31 7d 20 20 57 68 65 6e 20 5b 73 71 6c  7321}  When [sql
179f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e  ite3_realloc(P,N
17a00 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  )] returns a non
17a10 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69  -NULL pointer, i
17a20 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20  t first.**      
17a30 20 20 20 20 20 63 6f 70 69 65 73 20 74 68 65 20       copies the 
17a40 66 69 72 73 74 20 4b 20 62 79 74 65 73 20 6f 66  first K bytes of
17a50 20 63 6f 6e 74 65 6e 74 20 66 72 6f 6d 20 50 20   content from P 
17a60 69 6e 74 6f 20 74 68 65 20 6e 65 77 6c 79 0a 2a  into the newly.*
17a70 2a 20 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f  *           allo
17a80 63 61 74 65 64 20 62 6c 6f 63 6b 2c 20 77 68 65  cated block, whe
17a90 72 65 20 4b 20 69 73 20 74 68 65 20 6c 65 73 73  re K is the less
17aa0 65 72 20 6f 66 20 4e 20 61 6e 64 20 74 68 65 20  er of N and the 
17ab0 73 69 7a 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20  size of.**      
17ac0 20 20 20 20 20 74 68 65 20 62 75 66 66 65 72 20       the buffer 
17ad0 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 32  P..**.** {H17322
17ae0 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  }  When [sqlite3
17af0 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72  _realloc(P,N)] r
17b00 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c  eturns a non-NUL
17b10 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69  L pointer, it fi
17b20 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rst.**          
17b30 20 72 65 6c 65 61 73 65 73 20 74 68 65 20 62 75   releases the bu
17b40 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ffer P..**.** {H
17b50 31 37 33 32 33 7d 20 20 57 68 65 6e 20 5b 73 71  17323}  When [sq
17b60 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c  lite3_realloc(P,
17b70 4e 29 5d 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  N)] returns NULL
17b80 2c 20 74 68 65 20 62 75 66 66 65 72 20 50 20 69  , the buffer P i
17b90 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e  s.**           n
17ba0 6f 74 20 6d 6f 64 69 66 69 65 64 20 6f 72 20 72  ot modified or r
17bb0 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 41  eleased..**.** A
17bc0 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  SSUMPTIONS:.**.*
17bd0 2a 20 7b 41 31 37 33 35 30 7d 20 20 54 68 65 20  * {A17350}  The 
17be0 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
17bf0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
17c00 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
17c10 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
17c20 20 20 20 20 20 20 20 20 20 20 20 6d 75 73 74 20             must 
17c30 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
17c40 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
17c50 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
17c60 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  prior.**        
17c70 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66     invocation of
17c80 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
17c90 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
17ca0 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
17cb0 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  have.**         
17cc0 20 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72    not yet been r
17cd0 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  eleased..**.** {
17ce0 41 31 37 33 35 31 7d 20 20 54 68 65 20 61 70 70  A17351}  The app
17cf0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
17d00 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
17d10 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 20  any part of.**  
17d20 20 20 20 20 20 20 20 20 20 61 20 62 6c 6f 63 6b           a block
17d30 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
17d40 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
17d50 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20  eased using.**  
17d60 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
17d70 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
17d80 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
17d90 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
17da0 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
17db0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
17dc0 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
17dd0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
17de0 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  free(void*);../*
17df0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
17e00 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
17e10 74 61 74 69 73 74 69 63 73 20 7b 48 31 37 33 37  tatistics {H1737
17e20 30 7d 20 3c 53 33 30 32 31 30 3e 0a 2a 2a 0a 2a  0} <S30210>.**.*
17e30 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
17e40 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
17e50 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
17e60 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
17e70 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
17e80 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
17e90 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
17ea0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
17eb0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
17ec0 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
17ed0 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
17ee0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
17ef0 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
17f00 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
17f10 2a 0a 2a 2a 20 7b 48 31 37 33 37 31 7d 20 54 68  *.** {H17371} Th
17f20 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
17f30 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
17f40 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
17f50 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
17f60 20 20 20 20 20 20 20 20 20 20 6f 66 20 6d 65 6d            of mem
17f70 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
17f80 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
17f90 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
17fa0 64 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37  d)..**.** {H1737
17fb0 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
17fc0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
17fd0 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
17fe0 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
17ff0 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
18000 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65  e of [sqlite3_me
18010 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e  mory_used()] sin
18020 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  ce the high-wate
18030 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20  r mark.**       
18040 20 20 20 77 61 73 20 6c 61 73 74 20 72 65 73 65     was last rese
18050 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 34  t..**.** {H17374
18060 7d 20 54 68 65 20 76 61 6c 75 65 73 20 72 65 74  } The values ret
18070 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
18080 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
18090 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
180a0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
180b0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e  _highwater()] in
180c0 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65  clude any overhe
180d0 61 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ad.**          a
180e0 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
180f0 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
18100 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
18110 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20  _malloc()],.**  
18120 20 20 20 20 20 20 20 20 62 75 74 20 6e 6f 74 20          but not 
18130 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
18140 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
18150 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
18160 61 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ary.**          
18170 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
18180 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
18190 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a   may call..**.**
181a0 20 7b 48 31 37 33 37 35 7d 20 54 68 65 20 6d 65   {H17375} The me
181b0 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20  mory high-water 
181c0 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f  mark is reset to
181d0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
181e0 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  ue of.**        
181f0 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72    [sqlite3_memor
18200 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
18210 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
18220 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20  ameter to.**    
18230 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d        [sqlite3_m
18240 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
18250 29 5d 20 69 73 20 74 72 75 65 2e 20 20 54 68 65  )] is true.  The
18260 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
18270 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 5b  **          by [
18280 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
18290 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
182a0 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
182b0 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ark.**          
182c0 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
182d0 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  et..*/.sqlite3_i
182e0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
182f0 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
18300 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
18310 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
18320 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
18330 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
18340 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
18350 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
18360 65 72 61 74 6f 72 20 7b 48 31 37 33 39 30 7d 20  erator {H17390} 
18370 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 53  <S20000>.**.** S
18380 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61  QLite contains a
18390 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73   high-quality ps
183a0 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62  eudo-random numb
183b0 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52  er generator (PR
183c0 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73  NG) used to.** s
183d0 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 52 4f 57  elect random ROW
183e0 49 44 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69  IDs when inserti
183f0 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
18400 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
18410 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
18420 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
18430 73 69 62 6c 65 20 52 4f 57 49 44 2e 20 20 54 68  sible ROWID.  Th
18440 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
18450 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
18460 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
18470 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
18480 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
18490 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
184a0 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
184b0 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
184c0 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
184d0 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
184e0 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  es..**.** A call
184f0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
18500 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
18510 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
18520 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a  to buffer P..**.
18530 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69 6d  ** The first tim
18540 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
18550 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65  s invoked (eithe
18560 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20  r internally or 
18570 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  by.** the applic
18580 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20  ation) the PRNG 
18590 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  is seeded using 
185a0 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
185b0 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ned.** from the 
185c0 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68  xRandomness meth
185d0 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
185e0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
185f0 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c  object..** On al
18600 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  l subsequent inv
18610 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73  ocations, the ps
18620 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20  eudo-randomness 
18630 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20  is generated.** 
18640 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77  internally and w
18650 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20  ithout recourse 
18660 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
18670 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73  vfs] xRandomness
18680 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a  .** method..**.*
18690 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
186a0 0a 2a 2a 20 7b 48 31 37 33 39 32 7d 20 54 68 65  .** {H17392} The
186b0 20 5b 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d   [sqlite3_random
186c0 6e 65 73 73 28 4e 2c 50 29 5d 20 69 6e 74 65 72  ness(N,P)] inter
186d0 66 61 63 65 20 77 72 69 74 65 73 20 4e 20 62 79  face writes N by
186e0 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  tes of.**       
186f0 20 20 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20     high-quality 
18700 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
18710 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e  s into buffer P.
18720 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
18730 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
18740 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
18750 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
18760 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
18770 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
18780 6b 73 20 7b 48 31 32 35 30 30 7d 20 3c 53 37 30  ks {H12500} <S70
18790 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  100>.**.** This 
187a0 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72  routine register
187b0 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63  s a authorizer c
187c0 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70  allback with a p
187d0 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
187e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
187f0 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20  n], supplied in 
18800 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
18810 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  nt..** The autho
18820 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
18830 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
18840 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
18850 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
18860 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
18870 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
18880 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
18890 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
188a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
188b0 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73  pare16()] and [s
188c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
188d0 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72 69  _v2()].  At vari
188e0 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
188f0 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
18900 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
18910 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
18920 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
18930 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
18940 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
18950 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
18960 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
18970 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
18980 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
18990 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  .  The authorize
189a0 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
189b0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
189c0 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
189d0 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
189e0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
189f0 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
18a00 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
18a10 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
18a20 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
18a30 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
18a40 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
18a50 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
18a60 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
18a70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
18a80 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
18a90 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
18aa0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
18ab0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
18ac0 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
18ad0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
18ae0 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
18af0 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
18b00 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
18b10 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
18b20 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
18b30 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
18b40 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
18b50 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
18b60 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
18b70 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
18b80 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
18b90 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
18ba0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
18bb0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
18bc0 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
18bd0 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 57 68 65  sted is ok.  Whe
18be0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
18bf0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
18c00 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71  ENY], the.** [sq
18c10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
18c20 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
18c30 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
18c40 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74  gered the.** aut
18c50 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
18c60 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
18c70 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69  message explaini
18c80 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73  ng that.** acces
18c90 73 20 69 73 20 64 65 6e 69 65 64 2e 20 20 49 66  s is denied.  If
18ca0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
18cb0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
18cc0 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
18cd0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
18ce0 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
18cf0 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
18d00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
18d10 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
18d20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
18d30 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
18d40 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
18d50 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
18d60 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
18d70 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
18d80 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
18d90 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
18da0 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
18db0 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
18dc0 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
18dd0 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
18de0 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
18df0 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
18e00 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
18e10 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  table..**.** The
18e20 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
18e30 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
18e40 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
18e50 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
18e60 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
18e70 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
18e80 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
18e90 69 6e 74 65 72 66 61 63 65 2e 20 54 68 65 20 73  interface. The s
18ea0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
18eb0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
18ec0 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
18ed0 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
18ee0 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
18ef0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
18f00 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
18f10 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
18f20 72 69 7a 65 64 2e 20 54 68 65 20 74 68 69 72 64  rized. The third
18f30 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
18f40 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
18f50 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
18f60 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
18f70 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
18f80 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
18f90 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75  .** details abou
18fa0 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
18fb0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
18fc0 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
18fd0 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
18fe0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
18ff0 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
19000 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
19010 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
19020 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
19030 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
19040 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
19050 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
19060 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
19070 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
19080 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
19090 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
190a0 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
190b0 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
190c0 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
190d0 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
190e0 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
190f0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
19100 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
19110 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
19120 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
19130 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
19140 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
19150 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
19160 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
19170 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
19180 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
19190 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
191a0 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
191b0 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
191c0 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
191d0 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
191e0 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
191f0 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
19200 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
19210 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
19220 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
19230 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
19240 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
19250 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
19260 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
19270 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
19280 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
19290 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
192a0 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
192b0 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
192c0 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
192d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
192e0 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
192f0 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
19300 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
19310 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
19320 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
19330 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
19340 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
19350 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67  *.** Only a sing
19360 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
19370 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
19380 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
19390 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
193a0 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
193b0 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
193c0 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
193d0 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
193e0 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69 73 61 62  ous call.  Disab
193f0 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  le the authorize
19400 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20  r by installing 
19410 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e  a NULL callback.
19420 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
19430 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  er is disabled b
19440 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
19450 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
19460 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
19470 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
19480 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
19490 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
194a0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
194b0 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f  nvoked the autho
194c0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a  rizer callback..
194d0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
194e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
194f0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
19500 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
19510 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
19520 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19530 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
19540 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
19550 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
19560 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 5b 73 71  ..**.** When [sq
19570 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
19580 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70  ()] is used to p
19590 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
195a0 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  nt, the.** state
195b0 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65  ment might be re
195c0 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
195d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
195e0 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
195f0 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
19600 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
19610 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
19620 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
19630 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
19640 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
19650 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
19660 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
19670 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4e  step()]..**.** N
19680 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
19690 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
196a0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
196b0 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
196c0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
196d0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
196e0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
196f0 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
19700 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
19710 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
19720 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
19730 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
19740 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
19750 35 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  501} The [sqlite
19760 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
19770 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  (D,...)] interfa
19780 63 65 20 72 65 67 69 73 74 65 72 73 20 61 0a 2a  ce registers a.*
19790 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 68 6f  *          autho
197a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
197b0 69 74 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ith database con
197c0 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  nection D..**.**
197d0 20 7b 48 31 32 35 30 32 7d 20 54 68 65 20 61 75   {H12502} The au
197e0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
197f0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
19800 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
19810 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  re.**          b
19820 65 69 6e 67 20 70 61 72 73 65 65 64 20 61 6e 64  eing parseed and
19830 20 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a   compiled..**.**
19840 20 7b 48 31 32 35 30 33 7d 20 49 66 20 74 68 65   {H12503} If the
19850 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
19860 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 6e 79  back returns any
19870 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
19880 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  n.**          [S
19890 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
198a0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
198b0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
198c0 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  en.**          t
198d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
198e0 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 74 68  nterface call th
198f0 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 20 20 20  at caused.**    
19900 20 20 20 20 20 20 74 68 65 20 61 75 74 68 6f 72        the author
19910 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f  izer callback to
19920 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c 20   run shall fail 
19930 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20  with an.**      
19940 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f      [SQLITE_ERRO
19950 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  R] error code an
19960 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  d an appropriate
19970 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
19980 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 34 7d 20 57  **.** {H12504} W
19990 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hen the authoriz
199a0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
199b0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
199c0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
199d0 2a 20 20 20 20 20 20 20 20 20 20 64 65 73 63 72  *          descr
199e0 69 62 65 64 20 69 73 20 70 72 6f 63 65 73 73 65  ibed is processe
199f0 64 20 6e 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a  d normally..**.*
19a00 2a 20 7b 48 31 32 35 30 35 7d 20 57 68 65 6e 20  * {H12505} When 
19a10 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
19a20 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
19a30 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
19a40 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  he.**          a
19a50 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 74 65 72  pplication inter
19a60 66 61 63 65 20 63 61 6c 6c 20 74 68 61 74 20 63  face call that c
19a70 61 75 73 65 64 20 74 68 65 0a 2a 2a 20 20 20 20  aused the.**    
19a80 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72        authorizer
19a90 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e   callback to run
19aa0 20 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20   shall fail.**  
19ab0 20 20 20 20 20 20 20 20 77 69 74 68 20 61 6e 20          with an 
19ac0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65  [SQLITE_ERROR] e
19ad0 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e  rror code and an
19ae0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
19af0 2a 20 20 20 20 20 20 20 20 20 20 65 78 70 6c 61  *          expla
19b00 69 6e 69 6e 67 20 74 68 61 74 20 61 63 63 65 73  ining that acces
19b10 73 20 69 73 20 64 65 6e 69 65 64 2e 0a 2a 2a 0a  s is denied..**.
19b20 2a 2a 20 7b 48 31 32 35 30 36 7d 20 49 66 20 74  ** {H12506} If t
19b30 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  he authorizer co
19b40 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 61  de (the 2nd para
19b50 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
19b60 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20  horizer.**      
19b70 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 73      callback) is
19b80 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61   [SQLITE_READ] a
19b90 6e 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  nd the authorize
19ba0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
19bb0 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ns.**          [
19bc0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
19bd0 74 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 65  then the prepare
19be0 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  d statement is c
19bf0 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 0a 2a 2a  onstructed to.**
19c00 20 20 20 20 20 20 20 20 20 20 69 6e 73 65 72 74            insert
19c10 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
19c20 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
19c30 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
19c40 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 20 20  would have.**   
19c50 20 20 20 20 20 20 20 62 65 65 6e 20 72 65 61 64         been read
19c60 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
19c70 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
19c80 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 37  d..**.** {H12507
19c90 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69  } If the authori
19ca0 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e  zer code (the 2n
19cb0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
19cc0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a  he authorizer.**
19cd0 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
19ce0 63 6b 29 20 69 73 20 61 6e 79 74 68 69 6e 67 20  ck) is anything 
19cf0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
19d00 54 45 5f 52 45 41 44 5d 2c 20 74 68 65 6e 0a 2a  TE_READ], then.*
19d10 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65 74  *          a ret
19d20 75 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  urn of [SQLITE_I
19d30 47 4e 4f 52 45 5d 20 68 61 73 20 74 68 65 20 73  GNORE] has the s
19d40 61 6d 65 20 65 66 66 65 63 74 20 61 73 20 5b 53  ame effect as [S
19d50 51 4c 49 54 45 5f 44 45 4e 59 5d 2e 0a 2a 2a 0a  QLITE_DENY]..**.
19d60 2a 2a 20 7b 48 31 32 35 31 30 7d 20 54 68 65 20  ** {H12510} The 
19d70 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
19d80 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
19d90 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
19da0 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20  copy of.**      
19db0 20 20 20 20 74 68 65 20 74 68 69 72 64 20 70 61      the third pa
19dc0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
19dd0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
19de0 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
19df0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  ace..**.** {H125
19e00 31 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70  11} The second p
19e10 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
19e20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
19e30 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20  nteger.**       
19e40 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20     [SQLITE_COPY 
19e50 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
19e60 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68  hat specifies th
19e70 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
19e80 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
19e90 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
19ea0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 32 7d  ..**.** {H12512}
19eb0 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75   The third throu
19ec0 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  gh sixth paramet
19ed0 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ers to the callb
19ee0 61 63 6b 20 61 72 65 0a 2a 2a 20 20 20 20 20 20  ack are.**      
19ef0 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61      zero-termina
19f00 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
19f10 20 63 6f 6e 74 61 69 6e 0a 2a 2a 20 20 20 20 20   contain.**     
19f20 20 20 20 20 20 61 64 64 69 74 69 6f 6e 61 6c 20       additional 
19f30 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
19f40 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
19f50 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
19f60 20 7b 48 31 32 35 32 30 7d 20 45 61 63 68 20 63   {H12520} Each c
19f70 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
19f80 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
19f90 5d 20 6f 76 65 72 72 69 64 65 73 0a 2a 2a 20 20  ] overrides.**  
19fa0 20 20 20 20 20 20 20 20 61 6e 79 20 70 72 65 76          any prev
19fb0 69 6f 75 73 6c 79 20 69 6e 73 74 61 6c 6c 65 64  iously installed
19fc0 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
19fd0 2a 2a 20 7b 48 31 32 35 32 31 7d 20 41 20 4e 55  ** {H12521} A NU
19fe0 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 6d 65  LL authorizer me
19ff0 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 74 68  ans that no auth
1a000 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20 20 20  orization.**    
1a010 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 69        callback i
1a020 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
1a030 20 7b 48 31 32 35 32 32 7d 20 54 68 65 20 64 65   {H12522} The de
1a040 66 61 75 6c 74 20 61 75 74 68 6f 72 69 7a 65 72  fault authorizer
1a050 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   is NULL..*/.int
1a060 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1a070 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
1a080 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
1a090 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
1a0a0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1a0b0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1a0c0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
1a0d0 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
1a0e0 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
1a0f0 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
1a100 20 52 65 74 75 72 6e 20 43 6f 64 65 73 20 7b 48   Return Codes {H
1a110 31 32 35 39 30 7d 20 3c 48 31 32 35 30 30 3e 0a  12590} <H12500>.
1a120 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1a130 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1a140 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
1a150 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1a160 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
1a170 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
1a180 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
1a190 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
1a1a0 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
1a1b0 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
1a1c0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1a1d0 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
1a1e0 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
1a1f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
1a200 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1a210 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
1a220 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
1a230 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
1a240 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  tion..*/.#define
1a250 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31   SQLITE_DENY   1
1a260 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20     /* Abort the 
1a270 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69  SQL statement wi
1a280 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23  th an error */.#
1a290 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47  define SQLITE_IG
1a2a0 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27  NORE 2   /* Don'
1a2b0 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20  t allow access, 
1a2c0 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61  but don't genera
1a2d0 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a  te an error */..
1a2e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a2f0 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f  Authorizer Actio
1a300 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 35 30 7d  n Codes {H12550}
1a310 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H12500>.**.** 
1a320 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
1a330 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
1a340 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
1a350 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
1a360 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
1a370 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
1a380 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53  horize certain S
1a390 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
1a3a0 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
1a3b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
1a3c0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
1a3d0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
1a3e0 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
1a3f0 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
1a400 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
1a410 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
1a420 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
1a430 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
1a440 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1a450 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
1a460 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
1a470 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
1a480 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
1a490 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
1a4a0 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a  ation is to be.*
1a4b0 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
1a4c0 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
1a4d0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
1a4e0 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
1a4f0 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
1a500 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
1a510 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
1a520 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
1a530 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
1a540 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
1a550 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1a560 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 70 61  ter.  The 5th pa
1a570 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
1a580 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  * authorizer cal
1a590 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d  lback is the nam
1a5a0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
1a5b0 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e ("main", "temp
1a5c0 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61  ",.** etc.) if a
1a5d0 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65 20  pplicable.  The 
1a5e0 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
1a5f0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1a600 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
1a610 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
1a620 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
1a630 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
1a640 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
1a650 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
1a660 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
1a670 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
1a680 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
1a690 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
1a6a0 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
1a6b0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
1a6c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 31 7d 20  .**.** {H12551} 
1a6d0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1a6e0 65 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 20 20  eter to an.**   
1a6f0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1a700 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
1a710 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1a720 62 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20 61  back] shall be a
1a730 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20  n integer.**    
1a740 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f        [SQLITE_CO
1a750 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  PY | authorizer 
1a760 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
1a770 66 69 65 73 20 77 68 61 74 20 61 63 74 69 6f 6e  fies what action
1a780 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
1a790 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
1a7a0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 32 7d  ..**.** {H12552}
1a7b0 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
1a7c0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
1a7d0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
1a7e0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1a7f0 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
1a800 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 5d  zation callback]
1a810 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61  .**          sha
1a820 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
1a830 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
1a840 6e 67 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 20  ng on which.**  
1a850 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
1a860 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65  COPY | authorize
1a870 72 20 63 6f 64 65 5d 20 69 73 20 75 73 65 64 20  r code] is used 
1a880 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1a890 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
1a8a0 48 31 32 35 35 33 7d 20 54 68 65 20 35 74 68 20  H12553} The 5th 
1a8b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1a8c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1a8d0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1a8e0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
1a8f0 72 20 63 61 6c 6c 62 61 63 6b 5d 20 73 68 61 6c  r callback] shal
1a900 6c 20 62 65 20 74 68 65 20 6e 61 6d 65 0a 2a 2a  l be the name.**
1a910 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
1a920 20 64 61 74 61 62 61 73 65 20 28 65 78 61 6d 70   database (examp
1a930 6c 65 3a 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d  le: "main", "tem
1a940 70 22 2c 20 65 74 63 2e 29 20 69 66 20 61 70 70  p", etc.) if app
1a950 6c 69 63 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b  licable..**.** {
1a960 48 31 32 35 35 34 7d 20 54 68 65 20 36 74 68 20  H12554} The 6th 
1a970 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1a980 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1a990 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1a9a0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
1a9b0 72 20 63 61 6c 6c 62 61 63 6b 5d 20 73 68 61 6c  r callback] shal
1a9c0 6c 20 62 65 20 74 68 65 20 6e 61 6d 65 0a 2a 2a  l be the name.**
1a9d0 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
1a9e0 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67   inner-most trig
1a9f0 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74  ger or view that
1aa00 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
1aa10 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
1aa20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
1aa30 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
1aa40 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
1aa50 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
1aa60 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  om.**          t
1aa70 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64  op-level SQL cod
1aa80 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..*/./*********
1aa90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1aaa0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1aab0 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 3rd *********
1aac0 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 4th ********
1aad0 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ***/.#define SQL
1aae0 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58  ITE_CREATE_INDEX
1aaf0 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a            1   /*
1ab00 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1ab10 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1ab20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ab30 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20  TE_CREATE_TABLE 
1ab40 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20           2   /* 
1ab50 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1ab60 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1ab70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ab80 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e  E_CREATE_TEMP_IN
1ab90 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49  DEX     3   /* I
1aba0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1abb0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1abc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1abd0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42  _CREATE_TEMP_TAB
1abe0 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61  LE     4   /* Ta
1abf0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1ac00 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1ac10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ac20 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47  CREATE_TEMP_TRIG
1ac30 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69  GER   5   /* Tri
1ac40 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1ac50 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1ac60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1ac70 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20  REATE_TEMP_VIEW 
1ac80 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77       6   /* View
1ac90 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1aca0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1acb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1acc0 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20  EATE_TRIGGER    
1acd0 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67      7   /* Trigg
1ace0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1acf0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1ad00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1ad10 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20  ATE_VIEW        
1ad20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e     8   /* View N
1ad30 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1ad40 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1ad50 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45  fine SQLITE_DELE
1ad60 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
1ad70 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    9   /* Table N
1ad80 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1ad90 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1ada0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1adb0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
1adc0 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  10   /* Index Na
1add0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1ade0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1adf0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1ae00 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31  ABLE           1
1ae10 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  1   /* Table Nam
1ae20 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1ae30 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1ae40 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1ae50 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32  MP_INDEX      12
1ae60 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1ae70 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1ae80 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ae90 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1aea0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20  P_TABLE      13 
1aeb0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1aec0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1aed0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1aee0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1aef0 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20  _TRIGGER    14  
1af00 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1af10 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1af20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1af30 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1af40 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20  VIEW       15   
1af50 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1af60 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1af70 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1af80 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45  LITE_DROP_TRIGGE
1af90 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f  R         16   /
1afa0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1afb0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1afc0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1afd0 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20  ITE_DROP_VIEW   
1afe0 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a           17   /*
1aff0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1b000 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1b010 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b020 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20  TE_INSERT       
1b030 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20          18   /* 
1b040 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1b050 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1b060 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b070 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  E_PRAGMA        
1b080 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50         19   /* P
1b090 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31  ragma Name     1
1b0a0 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a  st arg or NULL *
1b0b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b0c0 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
1b0d0 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61        20   /* Ta
1b0e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
1b0f0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
1b100 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b110 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
1b120 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c       21   /* NUL
1b130 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
1b140 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1b150 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
1b160 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20  RANSACTION      
1b170 20 20 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c      22   /* NULL
1b180 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
1b190 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1b1a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50  define SQLITE_UP
1b1b0 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  DATE            
1b1c0 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65     23   /* Table
1b1d0 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
1b1e0 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
1b1f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54  efine SQLITE_ATT
1b200 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
1b210 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61    24   /* Filena
1b220 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  me        NULL  
1b230 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1b240 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41  fine SQLITE_DETA
1b250 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
1b260 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   25   /* Databas
1b270 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  e Name   NULL   
1b280 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1b290 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52  ine SQLITE_ALTER
1b2a0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1b2b0 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  26   /* Database
1b2c0 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61   Name   Table Na
1b2d0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1b2e0 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45  ne SQLITE_REINDE
1b2f0 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  X              2
1b300 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  7   /* Index Nam
1b310 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1b320 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1b330 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45  e SQLITE_ANALYZE
1b340 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38                28
1b350 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1b360 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1b370 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b380 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
1b390 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20  TABLE        29 
1b3a0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1b3b0 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
1b3c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b3d0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42  SQLITE_DROP_VTAB
1b3e0 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20  LE          30  
1b3f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1b400 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
1b410 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b420 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20  QLITE_FUNCTION  
1b430 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20             31   
1b440 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65  /* Function Name
1b450 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1b460 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b470 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
1b480 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
1b490 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
1b4a0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
1b4b0 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
1b4c0 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
1b4d0 69 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c 53  ions {H12280} <S
1b4e0 36 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49  60400>.** EXPERI
1b4f0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65  MENTAL.**.** The
1b500 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
1b510 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
1b520 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
1b530 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
1b540 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
1b550 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
1b560 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
1b570 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ments..**.** The
1b580 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1b590 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
1b5a0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1b5b0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a   is invoked at.*
1b5c0 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20  * various times 
1b5d0 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  when an SQL stat
1b5e0 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72  ement is being r
1b5f0 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  un by [sqlite3_s
1b600 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63  tep()]..** The c
1b610 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1b620 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
1b630 67 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61  g of the SQL sta
1b640 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61  tement text.** a
1b650 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
1b660 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
1b670 63 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  cuting.  Additio
1b680 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63  nal callbacks oc
1b690 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
1b6a0 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
1b6b0 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
1b6c0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
1b6d0 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
1b6e0 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
1b6f0 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
1b700 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
1b710 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  rigger..**.** Th
1b720 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1b730 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1b740 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
1b750 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
1b760 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
1b770 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
1b780 2e 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20 63  .  The profile c
1b790 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
1b7a0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
1b7b0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
1b7c0 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
1b7d0 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
1b7e0 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
1b7f0 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
1b800 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a   took to run..**
1b810 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1b820 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 31 7d 20 54  **.** {H12281} T
1b830 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1b840 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
1b850 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  by [sqlite3_trac
1b860 65 28 29 5d 20 0a 2a 2a 20 20 20 20 20 20 20 20  e()] .**        
1b870 20 20 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b    shall be invok
1b880 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  ed.**          w
1b890 68 65 6e 65 76 65 72 20 61 6e 20 53 51 4c 20 73  henever an SQL s
1b8a0 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
1b8b0 65 67 69 6e 73 20 74 6f 20 65 78 65 63 75 74 65  egins to execute
1b8c0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
1b8d0 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 69 67   whenever a trig
1b8e0 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 20 66  ger subprogram f
1b8f0 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20 72  irst begins to r
1b900 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38  un..**.** {H1228
1b910 32 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  2} Each call to 
1b920 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
1b930 5d 20 73 68 61 6c 6c 20 6f 76 65 72 72 69 64 65  ] shall override
1b940 20 74 68 65 20 70 72 65 76 69 6f 75 73 6c 79 0a   the previously.
1b950 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
1b960 73 74 65 72 65 64 20 74 72 61 63 65 20 63 61 6c  stered trace cal
1b970 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  lback..**.** {H1
1b980 32 32 38 33 7d 20 41 20 4e 55 4c 4c 20 74 72 61  2283} A NULL tra
1b990 63 65 20 63 61 6c 6c 62 61 63 6b 20 73 68 61 6c  ce callback shal
1b9a0 6c 20 64 69 73 61 62 6c 65 20 74 72 61 63 69 6e  l disable tracin
1b9b0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 34  g..**.** {H12284
1b9c0 7d 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  } The first argu
1b9d0 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63  ment to the trac
1b9e0 65 20 63 61 6c 6c 62 61 63 6b 20 73 68 61 6c 6c  e callback shall
1b9f0 20 62 65 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   be a copy of.**
1ba00 20 20 20 20 20 20 20 20 20 20 74 68 65 20 70 6f            the po
1ba10 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20  inter which was 
1ba20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74  the 3rd argument
1ba30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   to [sqlite3_tra
1ba40 63 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ce()]..**.** {H1
1ba50 32 32 38 35 7d 20 54 68 65 20 73 65 63 6f 6e 64  2285} The second
1ba60 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
1ba70 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
1ba80 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  is a.**         
1ba90 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1baa0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 63 6f   UTF-8 string co
1bab0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6f 72 69  ntaining the ori
1bac0 67 69 6e 61 6c 20 74 65 78 74 0a 2a 2a 20 20 20  ginal text.**   
1bad0 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 53 51         of the SQ
1bae0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69  L statement as i
1baf0 74 20 77 61 73 20 70 61 73 73 65 64 20 69 6e 74  t was passed int
1bb00 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
1bb10 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20  re_v2()].**     
1bb20 20 20 20 20 20 6f 72 20 74 68 65 20 65 71 75 69       or the equi
1bb30 76 61 6c 65 6e 74 2c 20 6f 72 20 61 6e 20 53 51  valent, or an SQ
1bb40 4c 20 63 6f 6d 6d 65 6e 74 20 69 6e 64 69 63 61  L comment indica
1bb50 74 69 6e 67 20 74 68 65 20 62 65 67 69 6e 6e 69  ting the beginni
1bb60 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ng.**          o
1bb70 66 20 61 20 74 72 69 67 67 65 72 20 73 75 62 70  f a trigger subp
1bb80 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  rogram..**.** {H
1bb90 31 32 32 38 37 7d 20 54 68 65 20 63 61 6c 6c 62  12287} The callb
1bba0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1bbb0 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69  istered by [sqli
1bbc0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 69  te3_profile()] i
1bbd0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20  s invoked.**    
1bbe0 20 20 20 20 20 20 61 73 20 65 61 63 68 20 53 51        as each SQ
1bbf0 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
1bc00 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  shes..**.** {H12
1bc10 32 38 38 7d 20 54 68 65 20 66 69 72 73 74 20 70  288} The first p
1bc20 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1bc30 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
1bc40 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   is a copy of.**
1bc50 20 20 20 20 20 20 20 20 20 20 74 68 65 20 33 72            the 3r
1bc60 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
1bc70 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
1bc80 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38  )]..**.** {H1228
1bc90 39 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  9} The second pa
1bca0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70  rameter to the p
1bcb0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
1bcc0 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  is a.**         
1bcd0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1bce0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
1bcf0 61 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  at contains the 
1bd00 63 6f 6d 70 6c 65 74 65 20 74 65 78 74 20 6f 66  complete text of
1bd10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1bd20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
1bd30 73 20 69 74 20 77 61 73 20 70 72 6f 63 65 73 73  s it was process
1bd40 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ed by [sqlite3_p
1bd50 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20  repare_v2()].** 
1bd60 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
1bd70 65 71 75 69 76 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a  equivalent..**.*
1bd80 2a 20 7b 48 31 32 32 39 30 7d 20 54 68 65 20 74  * {H12290} The t
1bd90 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
1bda0 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61  o the profile ca
1bdb0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 65 73 74  llback is an est
1bdc0 69 6d 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20  imate.**        
1bdd0 20 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20    of the number 
1bde0 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 20 6f  of nanoseconds o
1bdf0 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
1be00 65 20 72 65 71 75 69 72 65 64 20 74 6f 0a 2a 2a  e required to.**
1be10 20 20 20 20 20 20 20 20 20 20 72 75 6e 20 74 68            run th
1be20 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1be30 66 72 6f 6d 20 73 74 61 72 74 20 74 6f 20 66 69  from start to fi
1be40 6e 69 73 68 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  nish..*/.SQLITE_
1be50 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
1be60 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
1be70 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
1be80 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
1be90 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
1bea0 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45  d*);.SQLITE_EXPE
1beb0 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73  RIMENTAL void *s
1bec0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
1bed0 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
1bee0 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
1bef0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
1bf00 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
1bf10 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1bf20 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
1bf30 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
1bf40 20 7b 48 31 32 39 31 30 7d 20 3c 53 36 30 34 30   {H12910} <S6040
1bf50 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
1bf60 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73  utine configures
1bf70 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
1bf80 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72  tion - the.** pr
1bf90 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
1bfa0 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  - that is invoke
1bfb0 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
1bfc0 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75  uring long.** ru
1bfd0 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b  nning calls to [
1bfe0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
1bff0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1c000 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1c010 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20  3_get_table()]. 
1c020 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
1c030 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
1c040 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
1c050 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
1c060 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
1c070 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ery..**.** If th
1c080 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
1c090 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
1c0a0 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
1c0b0 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
1c0c0 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
1c0d0 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
1c0e0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
1c0f0 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
1c100 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
1c110 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
1c120 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
1c130 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  ess handler must
1c140 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
1c150 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
1c160 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
1c170 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1c180 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72  t invoked the pr
1c190 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
1c1a0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
1c1b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1c1c0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1c1d0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
1c1e0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
1c1f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c200 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
1c210 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
1c220 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
1c230 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1c240 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31  TS:.**.** {H1291
1c250 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  1} The callback 
1c260 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1c270 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
1c280 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1c290 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  ).**          is
1c2a0 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
1c2b0 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
1c2c0 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
1c2d0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
1c2e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1c2f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 32 7d 20  .**.** {H12912} 
1c300 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  The progress cal
1c310 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1c320 20 6f 6e 63 65 20 66 6f 72 20 65 76 65 72 79 20   once for every 
1c330 4e 20 76 69 72 74 75 61 6c 0a 2a 2a 20 20 20 20  N virtual.**    
1c340 20 20 20 20 20 20 6d 61 63 68 69 6e 65 20 6f 70        machine op
1c350 63 6f 64 65 73 2c 20 77 68 65 72 65 20 4e 20 69  codes, where N i
1c360 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
1c370 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20  ument to.**     
1c380 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65       the [sqlite
1c390 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1c3a0 65 72 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  er()] call that 
1c3b0 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20  registered.**   
1c3c0 20 20 20 20 20 20 20 74 68 65 20 63 61 6c 6c 62         the callb
1c3d0 61 63 6b 2e 20 20 49 66 20 4e 20 69 73 20 6c 65  ack.  If N is le
1c3e0 73 73 20 74 68 61 6e 20 31 2c 20 73 71 6c 69 74  ss than 1, sqlit
1c3f0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1c400 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20 20 20 20  ler().**        
1c410 20 20 61 63 74 73 20 61 73 20 69 66 20 61 20 4e    acts as if a N
1c420 55 4c 4c 20 70 72 6f 67 72 65 73 73 20 68 61 6e  ULL progress han
1c430 64 6c 65 72 20 68 61 64 20 62 65 65 6e 20 73 70  dler had been sp
1c440 65 63 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  ecified..**.** {
1c450 48 31 32 39 31 33 7d 20 54 68 65 20 70 72 6f 67  H12913} The prog
1c460 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 74  ress callback it
1c470 73 65 6c 66 20 69 73 20 69 64 65 6e 74 69 66 69  self is identifi
1c480 65 64 20 62 79 20 74 68 65 20 74 68 69 72 64 0a  ed by the third.
1c490 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 67 75  **          argu
1c4a0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1c4b0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
1c4c0 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31  ()..**.** {H1291
1c4d0 34 7d 20 54 68 65 20 66 6f 75 72 74 68 20 61 72  4} The fourth ar
1c4e0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
1c4f0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1c500 65 72 28 29 20 69 73 20 61 0a 2a 2a 20 20 20 20  er() is a.**    
1c510 20 20 20 20 20 20 76 6f 69 64 20 70 6f 69 6e 74        void point
1c520 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
1c530 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
1c540 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  ck.**          f
1c550 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 74 69 6d  unction each tim
1c560 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e  e it is invoked.
1c570 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 35 7d 20  .**.** {H12915} 
1c580 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  If a call to [sq
1c590 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
1c5a0 73 75 6c 74 73 20 69 6e 20 66 65 77 65 72 20 74  sults in fewer t
1c5b0 68 61 6e 20 4e 20 6f 70 63 6f 64 65 73 0a 2a 2a  han N opcodes.**
1c5c0 20 20 20 20 20 20 20 20 20 20 62 65 69 6e 67 20            being 
1c5d0 65 78 65 63 75 74 65 64 2c 20 74 68 65 6e 20 74  executed, then t
1c5e0 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
1c5f0 62 61 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e  back is never in
1c600 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  voked..**.** {H1
1c610 32 39 31 36 7d 20 45 76 65 72 79 20 63 61 6c 6c  2916} Every call
1c620 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f   to [sqlite3_pro
1c630 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d  gress_handler()]
1c640 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65  .**          ove
1c650 72 77 72 69 74 65 73 20 61 6e 79 20 70 72 65 76  rwrites any prev
1c660 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65  iously registere
1c670 64 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  d progress handl
1c680 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31  er..**.** {H1291
1c690 37 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 65  7} If the progre
1c6a0 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  ss handler callb
1c6b0 61 63 6b 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ack is NULL then
1c6c0 20 6e 6f 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20   no progress.** 
1c6d0 20 20 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72           handler
1c6e0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
1c6f0 2a 2a 20 7b 48 31 32 39 31 38 7d 20 49 66 20 74  ** {H12918} If t
1c700 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
1c710 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 72  back returns a r
1c720 65 73 75 6c 74 20 6f 74 68 65 72 20 74 68 61 6e  esult other than
1c730 20 30 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20   0, then.**     
1c740 20 20 20 20 20 74 68 65 20 62 65 68 61 76 69 6f       the behavio
1c750 72 20 69 73 20 61 20 69 66 20 5b 73 71 6c 69 74  r is a if [sqlit
1c760 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20  e3_interrupt()] 
1c770 68 61 64 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e  had been called.
1c780 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 53 33  .**          <S3
1c790 30 35 30 30 3e 0a 2a 2f 0a 76 6f 69 64 20 73 71  0500>.*/.void sq
1c7a0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1c7b0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
1c7c0 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
1c7d0 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
1c7e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
1c7f0 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
1c800 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
1c810 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 32 30 30  {H12700} <S40200
1c820 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
1c830 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
1c840 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
1c850 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69  ile whose name i
1c860 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a  s given by the.*
1c870 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
1c880 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e 61 6d  ent. The filenam
1c890 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
1c8a0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
1c8b0 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
1c8c0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1c8d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
1c8e0 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
1c8f0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
1c900 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
1c910 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 41  ite3_open16(). A
1c920 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c930 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
1c940 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
1c950 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
1c960 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
1c970 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
1c980 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
1c990 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
1c9a0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1c9b0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
1c9c0 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
1c9d0 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
1c9e0 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
1c9f0 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
1ca00 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
1ca10 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
1ca20 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
1ca30 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  . If the databas
1ca40 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
1ca50 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
1ca60 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
1ca70 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
1ca80 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
1ca90 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
1caa0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
1cab0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  ed.  The.** [sql
1cac0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
1cad0 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
1cae0 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
1caf0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
1cb00 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
1cb10 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
1cb20 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
1cb30 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  error..**.** The
1cb40 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
1cb50 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  g for the databa
1cb60 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  se will be UTF-8
1cb70 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   if.** sqlite3_o
1cb80 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
1cb90 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61  _open_v2() is ca
1cba0 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d  lled and.** UTF-
1cbb0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
1cbc0 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73   byte order if s
1cbd0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
1cbe0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57  is used..**.** W
1cbf0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
1cc00 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
1cc10 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
1cc20 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
1cc30 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
1cc40 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
1cc50 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
1cc60 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
1cc70 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
1cc80 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
1cc90 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
1cca0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
1ccb0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
1ccc0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1ccd0 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
1cce0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
1ccf0 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
1cd00 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
1cd10 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
1cd20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
1cd30 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
1cd40 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
1cd50 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
1cd60 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67  ction.  The flag
1cd70 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20  s parameter can 
1cd80 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
1cd90 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
1cda0 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
1cdb0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
1cdc0 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
1cdd0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
1cde0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ] or [SQLITE_OPE
1cdf0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
1ce00 67 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  gs:.**.** <dl>.*
1ce10 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  * <dt>[SQLITE_OP
1ce20 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
1ce30 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1ce40 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1ce50 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
1ce60 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
1ce70 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
1ce80 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
1ce90 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
1cea0 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
1ceb0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
1cec0 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e  _READWRITE]</dt>
1ced0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
1cee0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
1cef0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
1cf00 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
1cf10 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a  le, or reading.*
1cf20 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69  * only if the fi
1cf30 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
1cf40 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
1cf50 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
1cf60 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73  In either.** cas
1cf70 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  e the database m
1cf80 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
1cf90 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  t, otherwise an 
1cfa0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1cfb0 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  d.</dd>.**.** <d
1cfc0 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
1cfd0 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
1cfe0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
1cff0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1d000 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1d010 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
1d020 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
1d030 20 69 73 20 63 72 65 61 74 65 73 20 69 74 20 69   is creates it i
1d040 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
1d050 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
1d060 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
1d070 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
1d080 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
1d090 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1d0a0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
1d0b0 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64  6().</dd>.** </d
1d0c0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
1d0d0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
1d0e0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1d0f0 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
1d100 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
1d110 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
1d120 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   or one of the c
1d130 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
1d140 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64  n above combined
1d150 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
1d160 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1d170 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  X] or [SQLITE_OP
1d180 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
1d190 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ags,.** then the
1d1a0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
1d1b0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
1d1c0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
1d1d0 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
1d1e0 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
1d1f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1d200 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
1d210 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
1d220 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1d230 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
1d240 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
1d250 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
1d260 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
1d270 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
1d280 74 2d 74 69 6d 65 2e 20 20 49 66 20 74 68 65 0a  t-time.  If the.
1d290 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1d2a0 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
1d2b0 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
1d2c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d2d0 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
1d2e0 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
1d2f0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
1d300 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
1d310 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
1d320 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
1d330 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
1d340 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
1d350 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65  *.** If the file
1d360 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
1d370 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
1d380 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
1d390 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
1d3a0 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
1d3b0 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
1d3c0 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  n.  This in-memo
1d3d0 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
1d3e0 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
1d3f0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1d400 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
1d410 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
1d420 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
1d430 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
1d440 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
1d450 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
1d460 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
1d470 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
1d480 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
1d490 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
1d4a0 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
1d4b0 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
1d4c0 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
1d4d0 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
1d4e0 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
1d4f0 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
1d500 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
1d510 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
1d520 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
1d530 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ity..**.** If th
1d540 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
1d550 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
1d560 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1d570 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
1d580 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
1d590 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 54  l be created.  T
1d5a0 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
1d5b0 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
1d5c0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
1d5d0 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
1d5e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1d5f0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
1d600 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  ed..**.** The fo
1d610 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
1d620 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1d630 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
1d640 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
1d650 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
1d660 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
1d670 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1d680 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
1d690 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
1d6a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
1d6b0 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20 74  hould use.  If t
1d6c0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1d6d0 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
1d6e0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
1d6f0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1d700 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
1d710 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  s used..**.** <b
1d720 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
1d730 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
1d740 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
1d750 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
1d760 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
1d770 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1d780 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
1d790 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
1d7a0 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
1d7b0 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
1d7c0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
1d7d0 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
1d7e0 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
1d7f0 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
1d800 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
1d810 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
1d820 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
1d830 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
1d840 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
1d850 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1d860 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1d870 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30  TS:.**.** {H1270
1d880 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
1d890 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
1d8a0 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
1d8b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1d8c0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1d8d0 20 69 6e 74 65 72 66 61 63 65 73 20 63 72 65 61   interfaces crea
1d8e0 74 65 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20  te a new.**     
1d8f0 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
1d900 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63  onnection] assoc
1d910 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 20 20  iated with.**   
1d920 20 20 20 20 20 20 20 74 68 65 20 64 61 74 61 62         the datab
1d930 61 73 65 20 66 69 6c 65 20 67 69 76 65 6e 20 69  ase file given i
1d940 6e 20 74 68 65 69 72 20 66 69 72 73 74 20 70 61  n their first pa
1d950 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
1d960 48 31 32 37 30 32 7d 20 54 68 65 20 66 69 6c 65  H12702} The file
1d970 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
1d980 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1d990 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20  UTF-8.**        
1d9a0 20 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f    for [sqlite3_o
1d9b0 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  pen()] and [sqli
1d9c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61  te3_open_v2()] a
1d9d0 6e 64 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20  nd as UTF-16.** 
1d9e0 20 20 20 20 20 20 20 20 20 69 6e 20 74 68 65 20           in the 
1d9f0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1da00 72 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  r for [sqlite3_o
1da10 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  pen16()]..**.** 
1da20 7b 48 31 32 37 30 33 7d 20 41 20 73 75 63 63 65  {H12703} A succe
1da30 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
1da40 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   of [sqlite3_ope
1da50 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
1da60 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20  pen16()],.**    
1da70 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65        or [sqlite
1da80 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 72 69  3_open_v2()] wri
1da90 74 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  tes a pointer to
1daa0 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20   a new.**       
1dab0 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
1dac0 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 2a 70  nection] into *p
1dad0 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  pDb..**.** {H127
1dae0 30 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  04} The [sqlite3
1daf0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1db00 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
1db10 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
1db20 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1db30 5d 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74  ] interfaces ret
1db40 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
1db50 75 70 6f 6e 20 73 75 63 63 65 73 73 2c 0a 2a 2a  upon success,.**
1db60 20 20 20 20 20 20 20 20 20 20 6f 72 20 61 6e 20            or an 
1db70 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
1db80 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c  or code] on fail
1db90 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ure..**.** {H127
1dba0 30 36 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20  06} The default 
1dbb0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  text encoding fo
1dbc0 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 65  r a new database
1dbd0 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a   created using.*
1dbe0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1dbf0 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b  te3_open()] or [
1dc00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1dc10 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  )] will be UTF-8
1dc20 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 37 7d  ..**.** {H12707}
1dc30 20 54 68 65 20 64 65 66 61 75 6c 74 20 74 65 78   The default tex
1dc40 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61  t encoding for a
1dc50 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 72   new database cr
1dc60 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20  eated using.**  
1dc70 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1dc80 5f 6f 70 65 6e 31 36 28 29 5d 20 77 69 6c 6c 20  _open16()] will 
1dc90 62 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  be UTF-16..**.**
1dca0 20 7b 48 31 32 37 30 39 7d 20 54 68 65 20 5b 73   {H12709} The [s
1dcb0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 46 2c 44 29  qlite3_open(F,D)
1dcc0 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65  ] interface is e
1dcd0 71 75 69 76 61 6c 65 6e 74 20 74 6f 0a 2a 2a 20  quivalent to.** 
1dce0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1dcf0 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c  3_open_v2(F,D,G,
1dd00 30 29 5d 20 77 68 65 72 65 20 74 68 65 20 47 20  0)] where the G 
1dd10 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
1dd20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
1dd30 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
1dd40 7c 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  |[SQLITE_OPEN_CR
1dd50 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  EATE]..**.** {H1
1dd60 32 37 31 31 7d 20 49 66 20 74 68 65 20 47 20 70  2711} If the G p
1dd70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
1dd80 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44  ite3_open_v2(F,D
1dd90 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20  ,G,V)] contains 
1dda0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1ddb0 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  bit value [SQLIT
1ddc0 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
1ddd0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1dde0 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20  se is opened.** 
1ddf0 20 20 20 20 20 20 20 20 20 66 6f 72 20 72 65 61           for rea
1de00 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  ding only..**.**
1de10 20 7b 48 31 32 37 31 32 7d 20 49 66 20 74 68 65   {H12712} If the
1de20 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   G parameter to 
1de30 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1de40 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61  (F,D,G,V)] conta
1de50 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ins the.**      
1de60 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53      bit value [S
1de70 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1de80 52 49 54 45 5d 20 74 68 65 6e 20 74 68 65 20 64  RITE] then the d
1de90 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1dea0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
1deb0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
1dec0 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
1ded0 72 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e  r for reading on
1dee0 6c 79 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20  ly if the.**    
1def0 20 20 20 20 20 20 66 69 6c 65 20 69 73 20 77 72        file is wr
1df00 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
1df10 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1df20 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ystem..**.** {H1
1df30 32 37 31 33 7d 20 49 66 20 74 68 65 20 47 20 70  2713} If the G p
1df40 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
1df50 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44  ite3_open_v2(F,D
1df60 2c 47 2c 56 29 5d 20 6f 6d 69 74 73 20 74 68 65  ,G,V)] omits the
1df70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74  .**          bit
1df80 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f   value [SQLITE_O
1df90 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20  PEN_CREATE] and 
1dfa0 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
1dfb0 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20  s not.**        
1dfc0 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69    previously exi
1dfd0 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
1dfe0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1dff0 7b 48 31 32 37 31 34 7d 20 49 66 20 74 68 65 20  {H12714} If the 
1e000 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  G parameter to [
1e010 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1e020 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69  F,D,G,V)] contai
1e030 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
1e040 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51     bit value [SQ
1e050 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1e060 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  ] and the databa
1e070 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20  se does not.**  
1e080 20 20 20 20 20 20 20 20 70 72 65 76 69 6f 75 73          previous
1e090 6c 79 20 65 78 69 73 74 2c 20 74 68 65 6e 20 61  ly exist, then a
1e0a0 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
1e0b0 65 20 74 6f 20 63 72 65 61 74 65 20 61 6e 64 0a  e to create and.
1e0c0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 69 74  **          init
1e0d0 69 61 6c 69 7a 65 20 74 68 65 20 64 61 74 61 62  ialize the datab
1e0e0 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ase..**.** {H127
1e0f0 31 37 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e  17} If the filen
1e100 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ame argument to 
1e110 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1e120 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
1e130 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  6()],.**        
1e140 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70    or [sqlite3_op
1e150 65 6e 5f 76 32 28 29 5d 20 69 73 20 22 3a 6d 65  en_v2()] is ":me
1e160 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20  mory:", then an 
1e170 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20  private,.**     
1e180 20 20 20 20 20 65 70 68 65 6d 65 72 61 6c 2c 20       ephemeral, 
1e190 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
1e1a0 73 65 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  se is created fo
1e1b0 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
1e1c0 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74  ..**          <t
1e1d0 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50  odo>Is SQLITE_OP
1e1e0 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45  EN_CREATE|SQLITE
1e1f0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
1e200 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20  required.**     
1e210 20 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f       in sqlite3_
1e220 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f  open_v2()?</todo
1e230 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 39 7d  >.**.** {H12719}
1e240 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65   If the filename
1e250 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65   is NULL or an e
1e260 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
1e270 6e 20 61 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20  n a private,.** 
1e280 20 20 20 20 20 20 20 20 20 65 70 68 65 6d 65 72           ephemer
1e290 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  al on-disk datab
1e2a0 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
1e2b0 74 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ted..**         
1e2c0 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45   <todo>Is SQLITE
1e2d0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c  _OPEN_CREATE|SQL
1e2e0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1e2f0 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20  TE required.**  
1e300 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74          in sqlit
1e310 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74  e3_open_v2()?</t
1e320 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  odo>.**.** {H127
1e330 32 31 7d 20 54 68 65 20 5b 64 61 74 61 62 61 73  21} The [databas
1e340 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 72  e connection] cr
1e350 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eated by [sqlite
1e360 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c  3_open_v2(F,D,G,
1e370 56 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  V)].**          
1e380 77 69 6c 6c 20 75 73 65 20 74 68 65 20 5b 73 71  will use the [sq
1e390 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1e3a0 74 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  t identified by 
1e3b0 74 68 65 20 56 20 70 61 72 61 6d 65 74 65 72 2c  the V parameter,
1e3c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
1e3d0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
1e3e0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1e3f0 20 69 66 20 56 20 69 73 20 61 20 4e 55 4c 4c 20   if V is a NULL 
1e400 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  pointer..**.** {
1e410 48 31 32 37 32 33 7d 20 54 77 6f 20 5b 64 61 74  H12723} Two [dat
1e420 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e430 73 5d 20 77 69 6c 6c 20 73 68 61 72 65 20 61 20  s] will share a 
1e440 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 20 69 66 20  common cache if 
1e450 62 6f 74 68 20 77 65 72 65 0a 2a 2a 20 20 20 20  both were.**    
1e460 20 20 20 20 20 20 6f 70 65 6e 65 64 20 77 69 74        opened wit
1e470 68 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 77  h the same VFS w
1e480 68 69 6c 65 20 5b 73 68 61 72 65 64 20 63 61 63  hile [shared cac
1e490 68 65 20 6d 6f 64 65 5d 20 77 61 73 20 65 6e 61  he mode] was ena
1e4a0 62 6c 65 64 20 61 6e 64 0a 2a 2a 20 20 20 20 20  bled and.**     
1e4b0 20 20 20 20 20 69 66 20 62 6f 74 68 20 66 69 6c       if both fil
1e4c0 65 6e 61 6d 65 73 20 63 6f 6d 70 61 72 65 20 65  enames compare e
1e4d0 71 75 61 6c 20 75 73 69 6e 67 20 6d 65 6d 63 6d  qual using memcm
1e4e0 70 28 29 20 61 66 74 65 72 20 68 61 76 69 6e 67  p() after having
1e4f0 20 62 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   been.**        
1e500 20 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 74    processed by t
1e510 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  he [sqlite3_vfs 
1e520 7c 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 5d  | xFullPathname]
1e530 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 56   method of the V
1e540 46 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  FS..*/.int sqlit
1e550 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
1e560 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
1e570 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
1e580 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
1e590 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
1e5a0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
1e5b0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
1e5c0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
1e5d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
1e5e0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
1e5f0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
1e600 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
1e610 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
1e620 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
1e630 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
1e640 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
1e650 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1e660 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
1e670 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
1e680 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
1e690 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
1e6a0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
1e6b0 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
1e6c0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
1e6d0 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
1e6e0 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
1e6f0 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
1e700 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
1e710 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
1e720 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
1e730 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
1e740 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
1e750 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
1e760 73 61 67 65 73 20 7b 48 31 32 38 30 30 7d 20 3c  sages {H12800} <
1e770 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S60200>.**.** Th
1e780 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
1e790 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
1e7a0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
1e7b0 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
1e7c0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
1e7d0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
1e7e0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1e7f0 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f   failed sqlite3_
1e800 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73  * API call.** as
1e810 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
1e820 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1e830 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f  tion]. If a prio
1e840 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
1e850 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73  d.** but the mos
1e860 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
1e870 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
1e880 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
1e890 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72  om.** sqlite3_er
1e8a0 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
1e8b0 69 6e 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74  ined.  The sqlit
1e8c0 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
1e8d0 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ode().** interfa
1e8e0 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65  ce is the same e
1e8f0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
1e900 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65  ways returns the
1e910 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72   .** [extended r
1e920 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e  esult code] even
1e930 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72   when extended r
1e940 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a  esult codes are.
1e950 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  ** disabled..**.
1e960 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
1e970 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
1e980 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
1e990 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
1e9a0 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
1e9b0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
1e9c0 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
1e9d0 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
1e9e0 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
1e9f0 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** Memory to ho
1ea00 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
1ea10 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
1ea20 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
1ea30 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
1ea40 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
1ea50 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
1ea60 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
1ea70 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
1ea80 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
1ea90 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
1eaa0 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
1eab0 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
1eac0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
1ead0 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
1eae0 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
1eaf0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ns..**.** When t
1eb00 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
1eb10 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
1eb20 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67  s in use, it mig
1eb30 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73  ht be the.** cas
1eb40 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20  e that a second 
1eb50 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20  error occurs on 
1eb60 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
1eb70 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  d in between.** 
1eb80 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20  the time of the 
1eb90 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20  first error and 
1eba0 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73  the call to thes
1ebb0 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  e interfaces..**
1ebc0 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65   When that happe
1ebd0 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ns, the second e
1ebe0 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70  rror will be rep
1ebf0 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73  orted since thes
1ec00 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
1ec10 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68  always report th
1ec20 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65  e most recent re
1ec30 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a  sult.  To avoid.
1ec40 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68  ** this, each th
1ec50 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20  read can obtain 
1ec60 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66  exclusive use of
1ec70 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
1ec80 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
1ec90 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  by invoking [sql
1eca0 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
1ecb0 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
1ecc0 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20  tex](D)) before 
1ecd0 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20  beginning.** to 
1ece0 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69  use D and invoki
1ecf0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
1ed00 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65  x_leave]([sqlite
1ed10 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
1ed20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c  after.** all cal
1ed30 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66  ls to the interf
1ed40 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65  aces listed here
1ed50 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a   are completed..
1ed60 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
1ed70 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
1ed80 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
1ed90 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
1eda0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
1edb0 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
1edc0 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
1edd0 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
1ede0 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
1edf0 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
1ee00 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
1ee10 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  not be set..**.*
1ee20 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1ee30 0a 2a 2a 20 7b 48 31 32 38 30 31 7d 20 54 68 65  .** {H12801} The
1ee40 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1ee50 65 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(D)] interface 
1ee60 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
1ee70 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ric.**          
1ee80 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
1ee90 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
1eea0 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  t code] for the 
1eeb0 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 0a 2a 2a  most recently.**
1eec0 20 20 20 20 20 20 20 20 20 20 66 61 69 6c 65 64            failed
1eed0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20   interface call 
1eee0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1eef0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
1ef00 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
1ef10 2a 2a 20 7b 48 31 32 38 30 32 7d 20 54 68 65 20  ** {H12802} The 
1ef20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
1ef30 64 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69 6e  d_errcode(D)] in
1ef40 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1ef50 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20  the numeric.**  
1ef60 20 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65          [extende
1ef70 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
1ef80 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
1ef90 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ntly.**         
1efa0 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63   failed interfac
1efb0 65 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  e call associate
1efc0 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
1efd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1efe0 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30   D..**.** {H1280
1eff0 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
1f000 65 72 72 6d 73 67 28 44 29 5d 20 61 6e 64 20 5b  errmsg(D)] and [
1f010 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1f020 28 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  (D)].**         
1f030 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75   interfaces retu
1f040 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
1f050 61 67 65 20 74 65 78 74 20 74 68 61 74 20 64 65  age text that de
1f060 73 63 72 69 62 65 73 0a 2a 2a 20 20 20 20 20 20  scribes.**      
1f070 20 20 20 20 74 68 65 20 65 72 72 6f 72 20 69 6e      the error in
1f080 20 74 68 65 20 6d 6f 73 74 6c 79 20 72 65 63 65   the mostly rece
1f090 6e 74 6c 79 20 66 61 69 6c 65 64 20 69 6e 74 65  ntly failed inte
1f0a0 72 66 61 63 65 20 63 61 6c 6c 2c 0a 2a 2a 20 20  rface call,.**  
1f0b0 20 20 20 20 20 20 20 20 65 6e 63 6f 64 65 64 20          encoded 
1f0c0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
1f0d0 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63  or UTF-16 respec
1f0e0 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tively..**.** {H
1f0f0 31 32 38 30 37 7d 20 54 68 65 20 73 74 72 69 6e  12807} The strin
1f100 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  gs returned by [
1f110 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1f120 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  ] and [sqlite3_e
1f130 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20  rrmsg16()].**   
1f140 20 20 20 20 20 20 20 61 72 65 20 76 61 6c 69 64         are valid
1f150 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
1f160 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
1f170 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   call..**.** {H1
1f180 32 38 30 38 7d 20 43 61 6c 6c 73 20 74 6f 20 41  2808} Calls to A
1f190 50 49 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  PI routines that
1f1a0 20 64 6f 20 6e 6f 74 20 72 65 74 75 72 6e 20 61   do not return a
1f1b0 6e 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  n error code.** 
1f1c0 20 20 20 20 20 20 20 20 20 28 65 78 61 6d 70 6c           (exampl
1f1d0 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  e: [sqlite3_data
1f1e0 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f 20 6e 6f  _count()]) do no
1f1f0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 68  t.**          ch
1f200 61 6e 67 65 20 74 68 65 20 65 72 72 6f 72 20 63  ange the error c
1f210 6f 64 65 20 6f 72 20 6d 65 73 73 61 67 65 20 72  ode or message r
1f220 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20  eturned by.**   
1f230 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1f240 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c  errcode()], [sql
1f250 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
1f260 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20  rcode()],.**    
1f270 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
1f280 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71  rrmsg()], or [sq
1f290 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1f2a0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 39  ]..**.** {H12809
1f2b0 7d 20 49 6e 74 65 72 66 61 63 65 73 20 74 68 61  } Interfaces tha
1f2c0 74 20 61 72 65 20 6e 6f 74 20 61 73 73 6f 63 69  t are not associ
1f2d0 61 74 65 64 20 77 69 74 68 20 61 20 73 70 65 63  ated with a spec
1f2e0 69 66 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20  ific.**         
1f2f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1f300 63 74 69 6f 6e 5d 20 28 65 78 61 6d 70 6c 65 73  ction] (examples
1f310 3a 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  :.**          [s
1f320 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
1f330 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 6e  ] or [sqlite3_en
1f340 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
1f350 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  e()].**         
1f360 20 64 6f 20 6e 6f 74 20 63 68 61 6e 67 65 20 74   do not change t
1f370 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
1f380 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
1f390 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f    [sqlite3_errco
1f3a0 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  de()], [sqlite3_
1f3b0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
1f3c0 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
1f3d0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1f3e0 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
1f3f0 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f  _errmsg16()]..*/
1f400 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72  .int sqlite3_err
1f410 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
1f420 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  );.int sqlite3_e
1f430 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
1f440 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f  sqlite3 *db);.co
1f450 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1f460 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33  3_errmsg(sqlite3
1f470 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
1f480 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1f490 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1f4a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
1f4b0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
1f4c0 74 20 7b 48 31 33 30 30 30 7d 20 3c 48 31 33 30  t {H13000} <H130
1f4d0 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  10>.** KEYWORDS:
1f4e0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
1f4f0 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
1f500 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
1f510 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
1f520 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
1f530 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
1f540 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
1f550 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
1f560 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
1f570 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
1f580 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
1f590 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
1f5a0 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
1f5b0 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
1f5c0 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
1f5d0 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
1f5e0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
1f5f0 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
1f600 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
1f610 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
1f620 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
1f630 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1f640 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
1f650 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
1f660 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
1f670 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
1f680 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
1f690 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
1f6a0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
1f6b0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
1f6c0 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
1f6d0 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
1f6e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1f6f0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
1f700 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
1f710 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
1f720 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
1f730 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
1f740 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
1f750 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
1f760 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
1f770 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
1f780 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
1f790 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1f7a0 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
1f7b0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
1f7c0 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
1f7d0 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
1f7e0 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
1f7f0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1f800 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
1f810 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
1f820 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
1f830 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
1f840 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
1f850 69 6d 65 20 4c 69 6d 69 74 73 20 7b 48 31 32 37  ime Limits {H127
1f860 36 30 7d 20 3c 53 32 30 36 30 30 3e 0a 2a 2a 0a  60} <S20600>.**.
1f870 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1f880 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
1f890 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
1f8a0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
1f8b0 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
1f8c0 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
1f8d0 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
1f8e0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1f8f0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
1f900 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f910 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
1f920 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
1f930 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
1f940 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1f950 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
1f960 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
1f970 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
1f980 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
1f990 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
1f9a0 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
1f9b0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
1f9c0 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
1f9d0 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
1f9e0 73 74 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e  struct.  The fun
1f9f0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1fa00 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a  e old limit..**.
1fa10 2a 2a 20 49 66 20 74 68 65 20 6e 65 77 20 6c 69  ** If the new li
1fa20 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
1fa30 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
1fa40 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
1fa50 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d  ..** For the lim
1fa60 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66 20 53  it category of S
1fa70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20  QLITE_LIMIT_XYZ 
1fa80 74 68 65 72 65 20 69 73 20 61 20 68 61 72 64 20  there is a hard 
1fa90 75 70 70 65 72 0a 2a 2a 20 62 6f 75 6e 64 20 73  upper.** bound s
1faa0 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d  et by a compile-
1fab0 74 69 6d 65 20 43 20 70 72 65 70 72 6f 63 65 73  time C preproces
1fac0 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20  sor macro named 
1fad0 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 2e 0a  SQLITE_MAX_XYZ..
1fae0 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
1faf0 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
1fb00 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
1fb10 58 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74  X_".).** Attempt
1fb20 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
1fb30 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
1fb40 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
1fb50 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
1fb60 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
1fb70 65 20 68 61 72 64 20 75 70 70 65 72 20 6c 69 6d  e hard upper lim
1fb80 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69  it..**.** Run ti
1fb90 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
1fba0 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
1fbb0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
1fbc0 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
1fbd0 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
1fbe0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
1fbf0 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
1fc00 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
1fc10 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
1fc20 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
1fc30 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
1fc40 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
1fc50 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
1fc60 62 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61  bbrowser that ha
1fc70 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
1fc80 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
1fc90 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
1fca0 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
1fcb0 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
1fcc0 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
1fcd0 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
1fce0 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
1fcf0 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
1fd00 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
1fd10 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
1fd20 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
1fd30 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
1fd40 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
1fd50 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
1fd60 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
1fd70 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
1fd80 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
1fd90 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
1fda0 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
1fdb0 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
1fdc0 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
1fdd0 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
1fde0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1fdf0 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
1fe00 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
1fe10 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
1fe20 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
1fe30 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
1fe40 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
1fe50 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
1fe60 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
1fe70 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
1fe80 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
1fe90 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
1fea0 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
1feb0 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
1fec0 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
1fed0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
1fee0 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  es..**.** INVARI
1fef0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
1ff00 37 36 32 7d 20 41 20 73 75 63 63 65 73 73 66 75  762} A successfu
1ff10 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
1ff20 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d  e3_limit(D,C,V)]
1ff30 20 77 68 65 72 65 20 56 20 69 73 0a 2a 2a 20 20   where V is.**  
1ff40 20 20 20 20 20 20 20 20 70 6f 73 69 74 69 76 65          positive
1ff50 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 69 6d   changes the lim
1ff60 69 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f  it on the size o
1ff70 66 20 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e  f construct C in
1ff80 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1ff90 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1ffa0 63 74 69 6f 6e 5d 20 44 20 74 6f 20 74 68 65 20  ction] D to the 
1ffb0 6c 65 73 73 65 72 20 6f 66 20 56 20 61 6e 64 20  lesser of V and 
1ffc0 74 68 65 20 68 61 72 64 20 75 70 70 65 72 0a 2a  the hard upper.*
1ffd0 2a 20 20 20 20 20 20 20 20 20 20 62 6f 75 6e 64  *          bound
1ffe0 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20   on the size of 
1fff0 43 20 74 68 61 74 20 69 73 20 73 65 74 20 61 74  C that is set at
20000 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 0a 2a   compile-time..*
20010 2a 0a 2a 2a 20 7b 48 31 32 37 36 36 7d 20 41 20  *.** {H12766} A 
20020 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
20030 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  to [sqlite3_limi
20040 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20  t(D,C,V)] where 
20050 56 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a  V is negative.**
20060 20 20 20 20 20 20 20 20 20 20 6c 65 61 76 65 73            leaves
20070 20 74 68 65 20 73 74 61 74 65 20 6f 66 20 74 68   the state of th
20080 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
20090 65 63 74 69 6f 6e 5d 20 44 20 75 6e 63 68 61 6e  ection] D unchan
200a0 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ged..**.** {H127
200b0 36 39 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  69} A successful
200c0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
200d0 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20  3_limit(D,C,V)] 
200e0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20  returns the.**  
200f0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
20100 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68   the limit on th
20110 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72  e size of constr
20120 75 63 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20  uct C in the.** 
20130 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
20140 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
20150 20 61 73 20 69 74 20 77 61 73 20 70 72 69 6f 72   as it was prior
20160 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e 0a 2a 2f   to the call..*/
20170 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d  .int sqlite3_lim
20180 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  it(sqlite3*, int
20190 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29   id, int newVal)
201a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
201b0 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69  F: Run-Time Limi
201c0 74 20 43 61 74 65 67 6f 72 69 65 73 20 7b 48 31  t Categories {H1
201d0 32 37 39 30 7d 20 3c 48 31 32 37 36 30 3e 0a 2a  2790} <H12760>.*
201e0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
201f0 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 6c 69  it category} {li
20200 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a  mit categories}.
20210 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
20220 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72  tants define var
20230 69 6f 75 73 20 61 73 70 65 63 74 73 20 6f 66 20  ious aspects of 
20240 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
20250 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20  ection].** that 
20260 63 61 6e 20 62 65 20 6c 69 6d 69 74 65 64 20 69  can be limited i
20270 6e 20 73 69 7a 65 20 62 79 20 63 61 6c 6c 73 20  n size by calls 
20280 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  to [sqlite3_limi
20290 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 6d 65 61  t()]..** The mea
202a0 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
202b0 69 6f 75 73 20 6c 69 6d 69 74 73 20 61 72 65 20  ious limits are 
202c0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
202d0 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
202e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
202f0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
20300 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
20310 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
20320 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
20330 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  w.<dd>.**.** <dt
20340 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  >SQLITE_LIMIT_SQ
20350 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  L_LENGTH</dt>.**
20360 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
20370 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51   length of an SQ
20380 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  L statement.</dd
20390 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
203a0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
203b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
203c0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
203d0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
203e0 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
203f0 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
20400 75 6c 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c  ult set of a SEL
20410 45 43 54 20 6f 72 20 74 68 65 20 6d 61 78 69 6d  ECT or the maxim
20420 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
20430 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
20440 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44  .** or in an ORD
20450 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
20460 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a  Y clause.</dd>.*
20470 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
20480 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
20490 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
204a0 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
204b0 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
204c0 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
204d0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
204e0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
204f0 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c  COMPOUND_SELECT<
20500 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
20510 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
20520 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
20530 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
20540 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  tement.</dd>.**.
20550 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
20560 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
20570 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
20580 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
20590 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
205a0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
205b0 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
205c0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
205d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  SQL statement.</
205e0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
205f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
20600 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
20610 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
20620 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
20630 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
20640 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
20650 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
20660 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
20670 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
20680 6e 75 6d 62 65 72 20 6f 66 20 61 74 74 61 63 68  number of attach
20690 65 64 20 64 61 74 61 62 61 73 65 73 2e 3c 2f 64  ed databases.</d
206a0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
206b0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
206c0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64  ATTERN_LENGTH</d
206d0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
206e0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
206f0 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75  the pattern argu
20700 6d 65 6e 74 20 74 6f 20 74 68 65 20 4c 49 4b 45  ment to the LIKE
20710 20 6f 72 0a 2a 2a 20 47 4c 4f 42 20 6f 70 65 72   or.** GLOB oper
20720 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ators.</dd>.**.*
20730 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
20740 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
20750 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ER</dt>.** <dd>T
20760 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
20770 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20 69  r of variables i
20780 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
20790 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62  nt that can.** b
207a0 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a  e bound.</dd>.**
207b0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
207c0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
207d0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
207e0 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
207f0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
20800 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
20810 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
20820 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
20830 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
20840 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
20850 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
20860 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
20870 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
20880 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
20890 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
208a0 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
208b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
208c0 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
208d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
208e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
208f0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
20900 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
20910 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20920 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
20930 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20940 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
20950 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
20960 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
20970 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
20980 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
20990 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
209a0 20 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    9../*.** CAPI3
209b0 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
209c0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
209d0 7b 48 31 33 30 31 30 7d 20 3c 53 31 30 30 30 30  {H13010} <S10000
209e0 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
209f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
20a00 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f  mpiler}.**.** To
20a10 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
20a20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66  query, it must f
20a30 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64  irst be compiled
20a40 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64   into a byte-cod
20a50 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69  e.** program usi
20a60 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  ng one of these 
20a70 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
20a80 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
20a90 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
20aa0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20ab0 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
20ac0 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 63 61  om a.** prior ca
20ad0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ll to [sqlite3_o
20ae0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
20af0 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 20 5b  _open_v2()] or [
20b00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
20b10 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  ]..**.** The sec
20b20 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
20b30 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
20b40 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
20b50 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
20b60 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
20b70 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
20b80 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
20b90 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
20ba0 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
20bb0 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
20bc0 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
20bd0 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
20be0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
20bf0 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
20c00 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 66  UTF-16..**.** If
20c10 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
20c20 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ent is less than
20c30 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c   zero, then zSql
20c40 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
20c50 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
20c60 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 49 66 20   terminator. If 
20c70 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
20c80 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  ative, then it i
20c90 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
20ca0 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65   number of  byte
20cb0 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
20cc0 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69 73  .  When nByte is
20cd0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
20ce0 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
20cf0 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
20d00 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
20d10 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
20d20 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
20d30 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
20d40 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
20d50 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
20d60 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
20d70 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
20d80 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
20d90 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
20da0 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
20db0 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
20dc0 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
20dd0 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
20de0 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
20df0 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
20e00 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
20e10 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
20e20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
20e30 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
20e40 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
20e50 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a  minator bytes..*
20e60 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 69 73 20  *.** *pzTail is 
20e70 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
20e80 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 20   the first byte 
20e90 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
20ea0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 53 51 4c  the.** first SQL
20eb0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
20ec0 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ql.  These routi
20ed0 6e 65 73 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65  nes only compile
20ee0 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 73 74   the first.** st
20ef0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c  atement in zSql,
20f00 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
20f10 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
20f20 77 68 61 74 20 72 65 6d 61 69 6e 73 0a 2a 2a 20  what remains.** 
20f30 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  uncompiled..**.*
20f40 2a 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66  * *ppStmt is lef
20f50 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
20f60 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
20f70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
20f80 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
20f90 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
20fa0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 49  ite3_step()].  I
20fb0 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
20fc0 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
20fd0 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
20fe0 20 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65   If the input te
20ff0 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
21000 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
21010 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
21020 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
21030 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
21040 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
21050 2e 0a 2a 2a 20 7b 41 31 33 30 31 38 7d 20 54 68  ..** {A13018} Th
21060 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
21070 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
21080 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
21090 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  the compiled.** 
210a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73  SQL statement us
210b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
210c0 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
210d0 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
210e0 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  ith it..**.** On
210f0 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54   success, [SQLIT
21100 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
21110 64 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  d, otherwise an 
21120 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
21130 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
21140 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
21150 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
21160 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
21170 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
21180 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
21190 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
211a0 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
211b0 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
211c0 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
211d0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
211e0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
211f0 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
21200 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49  iscouraged..** I
21210 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
21220 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
21230 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
21240 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
21250 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
21260 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
21270 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
21280 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
21290 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
212a0 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
212b0 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
212c0 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
212d0 76 65 20 61 20 64 69 66 66 65 72 65 6e 74 6c 79  ve a differently
212e0 20 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a   in two ways:.**
212f0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
21300 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
21310 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
21320 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
21330 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
21340 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
21350 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
21360 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
21370 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
21380 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
21390 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
213a0 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
213b0 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
213c0 20 20 49 66 20 74 68 65 20 73 63 68 65 6d 61 20    If the schema 
213d0 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a  has changed in.*
213e0 2a 20 61 20 77 61 79 20 74 68 61 74 20 6d 61 6b  * a way that mak
213f0 65 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  es the statement
21400 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64   no longer valid
21410 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
21420 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a  )] will still.**
21430 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
21440 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e  SCHEMA].  But un
21450 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20  like the legacy 
21460 62 65 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54  behavior, [SQLIT
21470 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20  E_SCHEMA] is.** 
21480 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f  now a fatal erro
21490 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  r.  Calling [sql
214a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
214b0 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f  )] again will no
214c0 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72  t make the.** er
214d0 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f  ror go away.  No
214e0 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33  te: use [sqlite3
214f0 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69  _errmsg()] to fi
21500 6e 64 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f  nd the text.** o
21510 66 20 74 68 65 20 70 61 72 73 69 6e 67 20 65 72  f the parsing er
21520 72 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74 73  ror that results
21530 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53   in an [SQLITE_S
21540 43 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a  CHEMA] return..*
21550 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
21560 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72  i>.** When an er
21570 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c  ror occurs, [sql
21580 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
21590 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
215a0 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20  the detailed.** 
215b0 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72  [error codes] or
215c0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
215d0 20 63 6f 64 65 73 5d 2e 20 20 54 68 65 20 6c 65   codes].  The le
215e0 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
215f0 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74  s that.** [sqlit
21600 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
21610 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
21620 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45  eneric [SQLITE_E
21630 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
21640 65 0a 2a 2a 20 61 6e 64 20 79 6f 75 20 77 6f 75  e.** and you wou
21650 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
21660 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
21670 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
21680 29 5d 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  )] in order.** t
21690 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
216a0 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
216b0 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68  he problem. With
216c0 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
216d0 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c  e.** interfaces,
216e0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
216f0 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
21700 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
21710 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
21720 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
21730 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
21740 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 31 7d  :.**.** {H13011}
21750 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   The [sqlite3_pr
21760 65 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 2e 2e  epare(db,zSql,..
21770 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  .)] and.**      
21780 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65      [sqlite3_pre
21790 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c  pare_v2(db,zSql,
217a0 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73  ...)] interfaces
217b0 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a   interpret the.*
217c0 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20  *          text 
217d0 69 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61  in their zSql pa
217e0 72 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d 38  rameter as UTF-8
217f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 32 7d  ..**.** {H13012}
21800 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   The [sqlite3_pr
21810 65 70 61 72 65 31 36 28 64 62 2c 7a 53 71 6c 2c  epare16(db,zSql,
21820 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20  ...)] and.**    
21830 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70        [sqlite3_p
21840 72 65 70 61 72 65 31 36 5f 76 32 28 64 62 2c 7a  repare16_v2(db,z
21850 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  Sql,...)] interf
21860 61 63 65 73 20 69 6e 74 65 72 70 72 65 74 20 74  aces interpret t
21870 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  he.**          t
21880 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71  ext in their zSq
21890 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 55  l parameter as U
218a0 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
218b0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
218c0 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 33 7d 20 49  **.** {H13013} I
218d0 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
218e0 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
218f0 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a  _prepare_v2(db,z
21900 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a  Sql,nByte,...)].
21910 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  **          and 
21920 69 74 73 20 76 61 72 69 61 6e 74 73 20 69 73 20  its variants is 
21930 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20  less than zero, 
21940 74 68 65 20 53 51 4c 20 74 65 78 74 20 69 73 0a  the SQL text is.
21950 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 61 64  **          read
21960 20 66 72 6f 6d 20 7a 53 71 6c 20 69 73 20 72 65   from zSql is re
21970 61 64 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  ad up to the fir
21980 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
21990 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31  or..**.** {H1301
219a0 34 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 20  4} If the nByte 
219b0 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
219c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
219d0 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e  db,zSql,nByte,..
219e0 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
219f0 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
21a00 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
21a10 2c 20 74 68 65 6e 20 61 74 20 6d 6f 73 74 20 6e  , then at most n
21a20 42 79 74 65 73 20 62 79 74 65 73 20 6f 66 0a 2a  Bytes bytes of.*
21a30 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 74  *          SQL t
21a40 65 78 74 20 69 73 20 72 65 61 64 20 66 72 6f 6d  ext is read from
21a50 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   zSql..**.** {H1
21a60 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c 69 74 65  3015} In [sqlite
21a70 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c  3_prepare_v2(db,
21a80 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61 69 6c 29  zSql,N,P,pzTail)
21a90 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
21aa0 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ts.**          i
21ab0 66 20 74 68 65 20 7a 53 71 6c 20 69 6e 70 75 74  f the zSql input
21ac0 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6d   text contains m
21ad0 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 53 51 4c  ore than one SQL
21ae0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20   statement.**   
21af0 20 20 20 20 20 20 20 61 6e 64 20 70 7a 54 61 69         and pzTai
21b00 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  l is not NULL, t
21b10 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
21b20 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
21b30 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
21b40 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20  first byte past 
21b50 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
21b60 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  irst SQL stateme
21b70 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a 2a 20 20  nt in zSql..**  
21b80 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 57 68          <todo>Wh
21b90 61 74 20 64 6f 65 73 20 2a 70 7a 54 61 69 6c 20  at does *pzTail 
21ba0 70 6f 69 6e 74 20 74 6f 20 69 66 20 74 68 65 72  point to if ther
21bb0 65 20 69 73 20 6f 6e 65 20 73 74 61 74 65 6d 65  e is one stateme
21bc0 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  nt?</todo>.**.**
21bd0 20 7b 48 31 33 30 31 36 7d 20 41 20 73 75 63 63   {H13016} A succ
21be0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
21bf0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21c00 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 70 70 53  v2(db,zSql,N,ppS
21c10 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  tmt,...)].**    
21c20 20 20 20 20 20 20 6f 72 20 6f 6e 65 20 6f 66 20        or one of 
21c30 69 74 73 20 76 61 72 69 61 6e 74 73 20 77 72 69  its variants wri
21c40 74 65 73 20 69 6e 74 6f 20 2a 70 70 53 74 6d 74  tes into *ppStmt
21c50 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
21c60 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  new.**          
21c70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
21c80 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69 6e 74 65  ent] or a pointe
21c90 72 20 74 6f 20 4e 55 4c 4c 20 69 66 20 7a 53 71  r to NULL if zSq
21ca0 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20  l contains.**   
21cb0 20 20 20 20 20 20 20 6e 6f 74 68 69 6e 67 20 6f         nothing o
21cc0 74 68 65 72 20 74 68 61 6e 20 77 68 69 74 65 73  ther than whites
21cd0 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  pace or comments
21ce0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 39 7d  ..**.** {H13019}
21cf0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   The [sqlite3_pr
21d00 65 70 61 72 65 5f 76 32 28 29 5d 20 69 6e 74 65  epare_v2()] inte
21d10 72 66 61 63 65 20 61 6e 64 20 69 74 73 20 76 61  rface and its va
21d20 72 69 61 6e 74 73 20 72 65 74 75 72 6e 0a 2a 2a  riants return.**
21d30 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
21d40 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61 70 70 72  E_OK] or an appr
21d50 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
21d60 6f 64 65 5d 20 75 70 6f 6e 20 66 61 69 6c 75 72  ode] upon failur
21d70 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 32 31  e..**.** {H13021
21d80 7d 20 42 65 66 6f 72 65 20 5b 73 71 6c 69 74 65  } Before [sqlite
21d90 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71  3_prepare(db,zSq
21da0 6c 2c 6e 42 79 74 65 2c 70 70 53 74 6d 74 2c 70  l,nByte,ppStmt,p
21db0 7a 54 61 69 6c 29 5d 20 6f 72 20 69 74 73 0a 2a  zTail)] or its.*
21dc0 2a 20 20 20 20 20 20 20 20 20 20 76 61 72 69 61  *          varia
21dd0 6e 74 73 20 72 65 74 75 72 6e 73 20 61 6e 20 65  nts returns an e
21de0 72 72 6f 72 20 28 61 6e 79 20 76 61 6c 75 65 20  rror (any value 
21df0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
21e00 54 45 5f 4f 4b 5d 29 2c 0a 2a 2a 20 20 20 20 20  TE_OK]),.**     
21e10 20 20 20 20 20 74 68 65 79 20 66 69 72 73 74 20       they first 
21e20 73 65 74 20 2a 70 70 53 74 6d 74 20 74 6f 20 4e  set *ppStmt to N
21e30 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
21e40 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
21e50 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
21e60 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
21e70 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
21e80 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
21e90 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
21ea0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
21eb0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
21ec0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
21ed0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
21ee0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
21ef0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
21f00 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
21f10 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
21f20 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
21f30 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
21f40 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
21f50 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
21f60 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
21f70 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
21f80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
21f90 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
21fa0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
21fb0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
21fc0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
21fd0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
21fe0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
21ff0 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
22000 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
22010 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
22020 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
22030 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
22040 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
22050 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
22060 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
22070 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
22080 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
22090 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
220a0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
220b0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
220c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
220d0 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
220e0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
220f0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
22100 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
22110 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
22120 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
22130 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
22140 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
22150 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
22160 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
22170 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
22180 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
22190 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
221a0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
221b0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
221c0 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
221d0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
221e0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
221f0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
22200 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
22210 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
22220 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
22230 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
22240 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
22250 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
22260 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
22270 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
22280 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
22290 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
222a0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
222b0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
222c0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
222d0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
222e0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
222f0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
22300 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
22310 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
22320 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
22330 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
22340 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
22350 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22360 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
22370 65 6d 65 6e 74 20 53 51 4c 20 7b 48 31 33 31 30  ement SQL {H1310
22380 30 7d 20 3c 48 31 33 30 30 30 3e 0a 2a 2a 0a 2a  0} <H13000>.**.*
22390 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
223a0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
223b0 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64  retrieve a saved
223c0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69   copy of the ori
223d0 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78  ginal.** SQL tex
223e0 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
223f0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
22400 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20  tement] if that 
22410 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a  statement was.**
22420 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
22430 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
22440 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
22450 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22460 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
22470 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
22480 2a 2a 20 7b 48 31 33 31 30 31 7d 20 49 66 20 74  ** {H13101} If t
22490 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
224a0 74 65 6d 65 6e 74 5d 20 70 61 73 73 65 64 20 61  tement] passed a
224b0 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
224c0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
224d0 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 77 61  qlite3_sql()] wa
224e0 73 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67  s compiled using
224f0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
22500 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
22510 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
22520 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
22530 5f 76 32 28 29 5d 2c 20 74 68 65 6e 20 5b 73 71  _v2()], then [sq
22540 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 72 65 74  lite3_sql()] ret
22550 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
22560 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
22570 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
22580 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
22590 67 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  g a UTF-8 render
225a0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
225b0 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  of the original 
225c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
225d0 2a 0a 2a 2a 20 7b 48 31 33 31 30 32 7d 20 49 66  *.** {H13102} If
225e0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
225f0 74 61 74 65 6d 65 6e 74 5d 20 70 61 73 73 65 64  tatement] passed
22600 20 61 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   as the argument
22610 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
22620 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20  [sqlite3_sql()] 
22630 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  was compiled usi
22640 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
22650 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
22660 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
22670 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
22680 29 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  )], then [sqlite
22690 33 5f 73 71 6c 28 29 5d 20 72 65 74 75 72 6e 73  3_sql()] returns
226a0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
226b0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 33 7d 20  .**.** {H13103} 
226c0 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72  The string retur
226d0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
226e0 73 71 6c 28 53 29 5d 20 69 73 20 76 61 6c 69 64  sql(S)] is valid
226f0 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a 20 20 20   until the.**   
22700 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
22710 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73   statement] S is
22720 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 5b   deleted using [
22730 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
22740 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  (S)]..*/.const c
22750 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
22760 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
22770 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
22780 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61  PI3REF: Dynamica
22790 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20  lly Typed Value 
227a0 4f 62 6a 65 63 74 20 7b 48 31 35 30 30 30 7d 20  Object {H15000} 
227b0 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S20200>.** KEYW
227c0 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
227d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
227e0 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
227f0 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
22800 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
22810 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
22820 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
22830 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
22840 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
22850 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
22860 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
22870 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
22880 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
22890 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
228a0 2e 20 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20  . Values stored 
228b0 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
228c0 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20   objects.** can 
228d0 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
228e0 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
228f0 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
22900 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  Bs, or NULL..**.
22910 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61  ** An sqlite3_va
22920 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62  lue object may b
22930 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63  e either "protec
22940 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65  ted" or "unprote
22950 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69  cted"..** Some i
22960 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
22970 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  e a protected sq
22980 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74  lite3_value.  Ot
22990 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  her interfaces.*
229a0 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69  * will accept ei
229b0 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64  ther a protected
229c0 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74   or an unprotect
229d0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
229e0 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72  ..** Every inter
229f0 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74  face that accept
22a00 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  s sqlite3_value 
22a10 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66  arguments specif
22a20 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  ies.** whether o
22a30 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65  r not it require
22a40 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  s a protected sq
22a50 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
22a60 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
22a70 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
22a80 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
22a90 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
22aa0 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
22ab0 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e   held.  A intern
22ac0 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  al mutex is held
22ad0 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64   for a protected
22ae0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
22af0 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20  e object but no 
22b00 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
22b10 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
22b20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
22b30 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51  e object.  If SQ
22b40 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
22b50 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68   to be single-th
22b60 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20  readed.** (with 
22b70 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
22b80 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b  FE=0] and with [
22b90 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
22ba0 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20  fe()] returning 
22bb0 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69  0).** or if SQLi
22bc0 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65  te is run in one
22bd0 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65   of reduced mute
22be0 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c  x modes .** [SQL
22bf0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
22c00 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c  ETHREAD] or [SQL
22c10 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
22c20 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20  THREAD].** then 
22c30 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74  there is no dist
22c40 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
22c50 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
22c60 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
22c70 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
22c80 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20  ts and they can 
22c90 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61  be used intercha
22ca0 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65  ngeably.  Howeve
22cb0 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75  r,.** for maximu
22cc0 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69  m code portabili
22cd0 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ty it is recomme
22ce0 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
22cf0 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20  ations.** still 
22d00 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
22d10 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 62 65 74  tion between bet
22d20 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
22d30 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
22d40 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
22d50 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65  objects even whe
22d60 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72  n not strictly r
22d70 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
22d80 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
22d90 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72   objects that ar
22da0 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61  e passed as para
22db0 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a  meters into the.
22dc0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
22dd0 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f  n of [applicatio
22de0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
22df0 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f  nctions] are pro
22e00 74 65 63 74 65 64 2e 0a 2a 2a 20 54 68 65 20 73  tected..** The s
22e10 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
22e20 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
22e30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
22e40 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
22e50 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
22e60 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
22e70 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
22e80 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
22e90 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
22ea0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
22eb0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
22ec0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
22ed0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
22ee0 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
22ef0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
22f00 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
22f10 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
22f20 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
22f30 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
22f40 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
22f50 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
22f60 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
22f70 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
22f80 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
22f90 6a 65 63 74 20 7b 48 31 36 30 30 31 7d 20 3c 53  ject {H16001} <S
22fa0 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20200>.**.** The
22fb0 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63   context in whic
22fc0 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  h an SQL functio
22fd0 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74  n executes is st
22fe0 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71  ored in an.** sq
22ff0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
23000 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e 74 65 72  ject.  A pointer
23010 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63   to an sqlite3_c
23020 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a  ontext object.**
23030 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74   is always first
23040 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61   parameter to [a
23050 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
23060 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
23070 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  ]..** The applic
23080 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
23090 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
230a0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70  mentation will p
230b0 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e  ass this.** poin
230c0 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f  ter through into
230d0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
230e0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20  e3_result_int | 
230f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29  sqlite3_result()
23100 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61  ],.** [sqlite3_a
23110 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
23120 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73  ()], [sqlite3_us
23130 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b  er_data()],.** [
23140 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
23150 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73  db_handle()], [s
23160 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
23170 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ta()],.** and/or
23180 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
23190 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70  xdata()]..*/.typ
231a0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
231b0 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69  te3_context sqli
231c0 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a  te3_context;../*
231d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69  .** CAPI3REF: Bi
231e0 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
231f0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
23200 6e 74 73 20 7b 48 31 33 35 30 30 7d 20 3c 53 37  nts {H13500} <S7
23210 30 33 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0300>.** KEYWORD
23220 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
23230 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
23240 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
23250 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
23260 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
23270 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
23280 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
23290 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
232a0 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c 20 73  .** In the SQL s
232b0 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74 6f 20  trings input to 
232c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
232d0 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76  _v2()] and its v
232e0 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65  ariants,.** lite
232f0 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c  rals may be repl
23300 61 63 65 64 20 62 79 20 61 20 70 61 72 61 6d 65  aced by a parame
23310 74 65 72 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  ter in one of th
23320 65 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a  ese forms:.**.**
23330 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
23340 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
23350 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
23360 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
23370 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
23380 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70  >.**.** In the p
23390 61 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73  arameter forms s
233a0 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69  hown above NNN i
233b0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74  s an integer lit
233c0 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56  eral,.** and VVV
233d0 20 69 73 20 61 6e 20 61 6c 70 68 61 2d 6e 75 6d   is an alpha-num
233e0 65 72 69 63 20 70 61 72 61 6d 65 74 65 72 20 6e  eric parameter n
233f0 61 6d 65 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ame. The values 
23400 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
23410 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
23420 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
23430 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
23440 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
23450 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
23460 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
23470 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
23480 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
23490 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
234a0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
234b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
234c0 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77   routines is alw
234d0 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ays.** a pointer
234e0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
234f0 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
23500 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
23510 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
23520 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
23530 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  iants..**.** The
23540 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
23550 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
23560 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
23570 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
23580 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51   The leftmost SQ
23590 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
235a0 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
235b0 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
235c0 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
235d0 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
235e0 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
235f0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
23600 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
23610 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
23620 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
23630 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
23640 2a 20 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20  * The index for 
23650 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73  named parameters
23660 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75   can be looked u
23670 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  p using the.** [
23680 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
23690 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20  ameter_index()] 
236a0 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20  API if desired. 
236b0 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f   The index.** fo
236c0 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
236d0 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
236e0 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20   of NNN..** The 
236f0 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62  NNN value must b
23700 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20  e between 1 and 
23710 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  the [sqlite3_lim
23720 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74  it()].** paramet
23730 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  er [SQLITE_LIMIT
23740 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
23750 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  ] (default value
23760 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  : 999)..**.** Th
23770 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
23780 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
23790 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
237a0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e  ameter..**.** In
237b0 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
237c0 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
237d0 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
237e0 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
237f0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
23800 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
23810 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
23820 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
23830 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
23840 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
23850 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
23860 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
23870 61 63 74 65 72 73 2e 0a 2a 2a 20 49 66 20 74 68  acters..** If th
23880 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
23890 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
238a0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
238b0 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
238c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
238d0 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
238e0 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
238f0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  or..**.** The fi
23900 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
23910 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
23920 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
23930 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
23940 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
23950 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
23960 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
23970 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
23980 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
23990 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
239a0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
239b0 74 2e 20 49 66 20 74 68 65 20 66 69 66 74 68 20  t. If the fifth 
239c0 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
239d0 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
239e0 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
239f0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
23a00 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
23a10 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
23a20 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
23a30 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
23a40 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
23a50 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66   be freed..** If
23a60 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
23a70 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
23a80 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
23a90 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
23aa0 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
23ab0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
23ac0 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
23ad0 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
23ae0 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
23af0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
23b00 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  returns..**.** T
23b10 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
23b20 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
23b30 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
23b40 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
23b50 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
23b60 74 68 20 7a 65 72 6f 65 73 2e 20 20 41 20 7a 65  th zeroes.  A ze
23b70 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69  roblob uses a fi
23b80 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  xed amount of me
23b90 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e  mory.** (just an
23ba0 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64   integer to hold
23bb0 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65   its size) while
23bc0 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f   it is being pro
23bd0 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62  cessed..** Zerob
23be0 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lobs are intende
23bf0 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c  d to serve as pl
23c00 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  aceholders for B
23c10 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
23c20 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
23c30 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20  ritten using.** 
23c40 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
23c50 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
23c60 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69   BLOB I/O] routi
23c70 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65 67 61 74 69  nes..** A negati
23c80 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
23c90 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
23ca0 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
23cb0 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54  th BLOB..**.** T
23cc0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
23cd0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  *() routines mus
23ce0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65  t be called afte
23cf0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
23d00 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64  epare_v2()] (and
23d10 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f   its variants) o
23d20 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
23d30 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72  ()] and.** befor
23d40 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
23d50 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20  )]..** Bindings 
23d60 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
23d70 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
23d80 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
23d90 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72  ..** Unbound par
23da0 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
23db0 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
23dc0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
23dd0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
23de0 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
23df0 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20  ess or an error 
23e00 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68  code if.** anyth
23e10 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20  ing goes wrong. 
23e20 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20   [SQLITE_RANGE] 
23e30 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
23e40 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
23e50 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
23e60 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f  range.  [SQLITE_
23e70 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
23e80 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
23e90 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45  ails..** [SQLITE
23ea0 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 74 20 62  _MISUSE] might b
23eb0 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  e returned if th
23ec0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
23ed0 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20   called on a.** 
23ee0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
23ef0 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e  that is the wron
23f00 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 68  g state or which
23f10 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 65   has already bee
23f20 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20  n finalized..** 
23f30 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73  Detection of mis
23f40 75 73 65 20 69 73 20 75 6e 72 65 6c 69 61 62 6c  use is unreliabl
23f50 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  e.  Applications
23f60 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65   should not depe
23f70 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f  nd.** on SQLITE_
23f80 4d 49 53 55 53 45 20 72 65 74 75 72 6e 73 2e 20  MISUSE returns. 
23f90 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 69   SQLITE_MISUSE i
23fa0 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e  s intended to in
23fb0 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f  dicate a.** a lo
23fc0 67 69 63 20 65 72 72 6f 72 20 69 6e 20 74 68 65  gic error in the
23fd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46   application.  F
23fe0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
23ff0 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
24000 2a 20 70 61 6e 69 63 20 72 61 74 68 65 72 20 74  * panic rather t
24010 68 61 6e 20 72 65 74 75 72 6e 20 53 51 4c 49 54  han return SQLIT
24020 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20  E_MISUSE..**.** 
24030 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
24040 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
24050 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
24060 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
24070 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
24080 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
24090 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
240a0 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  x()]..**.** INVA
240b0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
240c0 31 33 35 30 36 7d 20 54 68 65 20 5b 53 51 4c 20  13506} The [SQL 
240d0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
240e0 65 72 5d 20 72 65 63 6f 67 6e 69 7a 65 73 20 74  er] recognizes t
240f0 6f 6b 65 6e 73 20 6f 66 20 74 68 65 20 66 6f 72  okens of the for
24100 6d 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 22  ms.**          "
24110 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 24 56 56  ?", "?NNN", "$VV
24120 56 22 2c 20 22 3a 56 56 56 22 2c 20 61 6e 64 20  V", ":VVV", and 
24130 22 40 56 56 56 22 20 61 73 20 53 51 4c 20 70 61  "@VVV" as SQL pa
24140 72 61 6d 65 74 65 72 73 2c 0a 2a 2a 20 20 20 20  rameters,.**    
24150 20 20 20 20 20 20 77 68 65 72 65 20 4e 4e 4e 20        where NNN 
24160 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20  is any sequence 
24170 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 64  of one or more d
24180 69 67 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  igits.**        
24190 20 20 61 6e 64 20 77 68 65 72 65 20 56 56 56 20    and where VVV 
241a0 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20  is any sequence 
241b0 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 61  of one or more a
241c0 6c 70 68 61 6e 75 6d 65 72 69 63 0a 2a 2a 20 20  lphanumeric.**  
241d0 20 20 20 20 20 20 20 20 63 68 61 72 61 63 74 65          characte
241e0 72 73 20 6f 72 20 22 3a 3a 22 20 6f 70 74 69 6f  rs or "::" optio
241f0 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62  nally followed b
24200 79 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  y a string conta
24210 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  ining.**        
24220 20 20 6e 6f 20 73 70 61 63 65 73 20 61 6e 64 20    no spaces and 
24230 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e  contained within
24240 20 70 61 72 65 6e 74 68 65 73 65 73 2e 0a 2a 2a   parentheses..**
24250 0a 2a 2a 20 7b 48 31 33 35 30 39 7d 20 54 68 65  .** {H13509} The
24260 20 69 6e 69 74 69 61 6c 20 76 61 6c 75 65 20 6f   initial value o
24270 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
24280 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  er is NULL..**.*
24290 2a 20 7b 48 31 33 35 31 32 7d 20 54 68 65 20 69  * {H13512} The i
242a0 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 22 20 53  ndex of an "?" S
242b0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
242c0 6f 6e 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20  one larger than 
242d0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
242e0 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66  largest index of
242f0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
24300 6f 20 74 68 65 20 6c 65 66 74 2c 20 6f 72 20 31  o the left, or 1
24310 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
24320 74 68 65 20 22 3f 22 20 69 73 20 74 68 65 20 6c  the "?" is the l
24330 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
24340 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  meter..**.** {H1
24350 33 35 31 35 7d 20 54 68 65 20 69 6e 64 65 78 20  3515} The index 
24360 6f 66 20 61 6e 20 22 3f 4e 4e 4e 22 20 53 51 4c  of an "?NNN" SQL
24370 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
24380 65 20 69 6e 74 65 67 65 72 20 4e 4e 4e 2e 0a 2a  e integer NNN..*
24390 2a 0a 2a 2a 20 7b 48 31 33 35 31 38 7d 20 54 68  *.** {H13518} Th
243a0 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3a  e index of an ":
243b0 56 56 56 22 2c 20 22 24 56 56 56 22 2c 20 6f 72  VVV", "$VVV", or
243c0 20 22 40 56 56 56 22 20 53 51 4c 20 70 61 72 61   "@VVV" SQL para
243d0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20  meter is.**     
243e0 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 61 73       the same as
243f0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 6c 65   the index of le
24400 66 74 6d 6f 73 74 20 6f 63 63 75 72 72 65 6e 63  ftmost occurrenc
24410 65 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  es of the same.*
24420 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
24430 65 74 65 72 2c 20 6f 72 20 6f 6e 65 20 6d 6f 72  eter, or one mor
24440 65 20 74 68 61 6e 20 74 68 65 20 6c 61 72 67 65  e than the large
24450 73 74 20 69 6e 64 65 78 20 6f 76 65 72 20 61 6c  st index over al
24460 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  l.**          pa
24470 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
24480 6c 65 66 74 20 69 66 20 74 68 69 73 20 69 73 20  left if this is 
24490 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
244a0 65 6e 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  ence.**         
244b0 20 6f 66 20 74 68 69 73 20 70 61 72 61 6d 65 74   of this paramet
244c0 65 72 2c 20 6f 72 20 31 20 69 66 20 74 68 69 73  er, or 1 if this
244d0 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74   is the leftmost
244e0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
244f0 2a 20 7b 48 31 33 35 32 31 7d 20 54 68 65 20 5b  * {H13521} The [
24500 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
24510 6d 70 69 6c 65 72 5d 20 66 61 69 6c 73 20 77 69  mpiler] fails wi
24520 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 52 41  th an [SQLITE_RA
24530 4e 47 45 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  NGE].**         
24540 20 65 72 72 6f 72 20 69 66 20 74 68 65 20 69 6e   error if the in
24550 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
24560 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
24570 74 68 61 6e 20 31 0a 2a 2a 20 20 20 20 20 20 20  than 1.**       
24580 20 20 20 6f 72 20 67 72 65 61 74 65 72 20 74 68     or greater th
24590 61 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  an the compile-t
245a0 69 6d 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56  ime SQLITE_MAX_V
245b0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 0a 2a  ARIABLE_NUMBER.*
245c0 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
245d0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  eter..**.** {H13
245e0 35 32 34 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73  524} Calls to [s
245f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
24600 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28   | sqlite3_bind(
24610 53 2c 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  S,N,V,...)].**  
24620 20 20 20 20 20 20 20 20 61 73 73 6f 63 69 61 74          associat
24630 65 20 74 68 65 20 76 61 6c 75 65 20 56 20 77 69  e the value V wi
24640 74 68 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d  th all SQL param
24650 65 74 65 72 73 20 68 61 76 69 6e 67 20 61 6e 0a  eters having an.
24660 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 64 65  **          inde
24670 78 20 6f 66 20 4e 20 69 6e 20 74 68 65 20 5b 70  x of N in the [p
24680 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24690 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  t] S..**.** {H13
246a0 35 32 37 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73  527} Calls to [s
246b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
246c0 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28   | sqlite3_bind(
246d0 53 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  S,N,...)].**    
246e0 20 20 20 20 20 20 6f 76 65 72 72 69 64 65 20 70        override p
246f0 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 20  rior calls with 
24700 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20  the same values 
24710 6f 66 20 53 20 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a  of S and N..**.*
24720 2a 20 7b 48 31 33 35 33 30 7d 20 42 69 6e 64 69  * {H13530} Bindi
24730 6e 67 73 20 65 73 74 61 62 6c 69 73 68 65 64 20  ngs established 
24740 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  by [sqlite3_bind
24750 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f  _text | sqlite3_
24760 62 69 6e 64 28 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20  bind(S,...)].** 
24770 20 20 20 20 20 20 20 20 20 70 65 72 73 69 73 74           persist
24780 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f   across calls to
24790 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
247a0 53 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  S)]..**.** {H135
247b0 33 33 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20  33} In calls to 
247c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
247d0 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a  ob(S,N,V,L,D)],.
247e0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
247f0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53  ite3_bind_text(S
24800 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a  ,N,V,L,D)], or.*
24810 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
24820 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
24830 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69  S,N,V,L,D)] SQLi
24840 74 65 20 62 69 6e 64 73 20 74 68 65 20 66 69 72  te binds the fir
24850 73 74 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  st L.**         
24860 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c   bytes of the BL
24870 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 70 6f 69  OB or string poi
24880 6e 74 65 64 20 74 6f 20 62 79 20 56 2c 20 77 68  nted to by V, wh
24890 65 6e 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  en L.**         
248a0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
248b0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 36 7d  ..**.** {H13536}
248c0 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
248d0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
248e0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 6f 72 0a 2a  S,N,V,L,D)] or.*
248f0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
24900 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
24910 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69  S,N,V,L,D)] SQLi
24920 74 65 20 62 69 6e 64 73 20 63 68 61 72 61 63 74  te binds charact
24930 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ers.**          
24940 66 72 6f 6d 20 56 20 74 68 72 6f 75 67 68 20 74  from V through t
24950 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
24960 61 72 61 63 74 65 72 20 77 68 65 6e 20 4c 20 69  aracter when L i
24970 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  s negative..**.*
24980 2a 20 7b 48 31 33 35 33 39 7d 20 49 6e 20 63 61  * {H13539} In ca
24990 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
249a0 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  bind_blob(S,N,V,
249b0 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  L,D)],.**       
249c0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
249d0 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
249e0 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
249f0 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
24a00 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
24a10 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 65  )] when D is the
24a20 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20   special.**     
24a30 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53       constant [S
24a40 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 53  QLITE_STATIC], S
24a50 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
24a60 61 74 20 74 68 65 20 76 61 6c 75 65 20 56 0a 2a  at the value V.*
24a70 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 68 65  *          is he
24a80 6c 64 20 69 6e 20 73 74 61 74 69 63 20 75 6e 6d  ld in static unm
24a90 61 6e 61 67 65 64 20 73 70 61 63 65 20 74 68 61  anaged space tha
24aa0 74 20 77 69 6c 6c 20 6e 6f 74 20 63 68 61 6e 67  t will not chang
24ab0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 75  e.**          du
24ac0 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
24ad0 65 20 6f 66 20 74 68 65 20 62 69 6e 64 69 6e 67  e of the binding
24ae0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 32 7d  ..**.** {H13542}
24af0 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
24b00 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
24b10 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20  S,N,V,L,D)],.** 
24b20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
24b30 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
24b40 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,L,D)], or.**  
24b50 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
24b60 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
24b70 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20  ,V,L,D)] when D 
24b80 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a  is the special.*
24b90 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74  *          const
24ba0 61 6e 74 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  ant [SQLITE_TRAN
24bb0 53 49 45 4e 54 5d 2c 20 74 68 65 20 72 6f 75 74  SIENT], the rout
24bc0 69 6e 65 20 6d 61 6b 65 73 20 61 0a 2a 2a 20 20  ine makes a.**  
24bd0 20 20 20 20 20 20 20 20 70 72 69 76 61 74 65 20          private 
24be0 63 6f 70 79 20 6f 66 20 74 68 65 20 76 61 6c 75  copy of the valu
24bf0 65 20 56 20 62 65 66 6f 72 65 20 69 74 20 72 65  e V before it re
24c00 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  turns..**.** {H1
24c10 33 35 34 35 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3545} In calls t
24c20 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
24c30 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  blob(S,N,V,L,D)]
24c40 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
24c50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
24c60 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72  (S,N,V,L,D)], or
24c70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
24c80 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
24c90 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68  6(S,N,V,L,D)] wh
24ca0 65 6e 20 44 20 69 73 20 61 20 70 6f 69 6e 74 65  en D is a pointe
24cb0 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
24cc0 20 61 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c   a function, SQL
24cd0 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 61 74  ite invokes that
24ce0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 64 65 73   function to des
24cf0 74 72 6f 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  troy the.**     
24d00 20 20 20 20 20 76 61 6c 75 65 20 56 20 61 66 74       value V aft
24d10 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
24d20 65 64 20 75 73 69 6e 67 20 74 68 65 20 76 61 6c  ed using the val
24d30 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ue V..**.** {H13
24d40 35 34 38 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  548} In calls to
24d50 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a   [sqlite3_bind_z
24d60 65 72 6f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 29  eroblob(S,N,V,L)
24d70 5d 20 74 68 65 20 76 61 6c 75 65 20 62 6f 75 6e  ] the value boun
24d80 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  d.**          is
24d90 20 61 20 42 4c 4f 42 20 6f 66 20 4c 20 62 79 74   a BLOB of L byt
24da0 65 73 2c 20 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  es, or a zero-le
24db0 6e 67 74 68 20 42 4c 4f 42 20 69 66 20 4c 20 69  ngth BLOB if L i
24dc0 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  s negative..**.*
24dd0 2a 20 7b 48 31 33 35 35 31 7d 20 49 6e 20 63 61  * {H13551} In ca
24de0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
24df0 62 69 6e 64 5f 76 61 6c 75 65 28 53 2c 4e 2c 56  bind_value(S,N,V
24e00 29 5d 20 74 68 65 20 56 20 61 72 67 75 6d 65 6e  )] the V argumen
24e10 74 20 6d 61 79 0a 2a 2a 20 20 20 20 20 20 20 20  t may.**        
24e20 20 20 62 65 20 65 69 74 68 65 72 20 61 20 5b 70    be either a [p
24e30 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
24e40 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6f  _value] object o
24e50 72 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  r an.**         
24e60 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
24e70 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
24e80 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ect..*/.int sqli
24e90 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
24ea0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
24eb0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
24ec0 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
24ed0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
24ee0 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
24ef0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
24f00 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
24f10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
24f20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
24f30 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
24f40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
24f50 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
24f60 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
24f70 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
24f80 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
24f90 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
24fa0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
24fb0 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
24fc0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
24fd0 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
24fe0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
24ff0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
25000 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
25010 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
25020 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
25030 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
25040 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
25050 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
25060 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
25070 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
25080 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
25090 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
250a0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
250b0 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
250c0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
250d0 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
250e0 20 7b 48 31 33 36 30 30 7d 20 3c 53 37 30 33 30   {H13600} <S7030
250f0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
25100 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
25110 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
25120 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72  mber of [SQL par
25130 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61  ameters].** in a
25140 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25150 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61  ment].  SQL para
25160 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e  meters are token
25170 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
25180 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a   "?", "?NNN", ":
25190 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72  AAA", "$AAA", or
251a0 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72   "@AAA" that ser
251b0 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f  ve as.** placeho
251c0 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
251d0 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
251e0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
251f0 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
25200 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
25210 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
25220 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61  * This routine a
25230 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  ctually returns 
25240 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
25250 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d   largest (rightm
25260 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ost).** paramete
25270 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73  r. For all forms
25280 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68   except ?NNN, th
25290 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f  is will correspo
252a0 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d  nd to the.** num
252b0 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61  ber of unique pa
252c0 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61  rameters.  If pa
252d0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
252e0 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c 0a 2a  ?NNN are used,.*
252f0 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67  * there may be g
25300 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e  aps in the list.
25310 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
25320 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
25330 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
25340 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
25350 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
25360 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
25370 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
25380 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
25390 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
253a0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 30  TS:.**.** {H1360
253b0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
253c0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
253d0 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72 66 61  ount(S)] interfa
253e0 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  ce returns.**   
253f0 20 20 20 20 20 20 20 74 68 65 20 6c 61 72 67 65         the large
25400 73 74 20 69 6e 64 65 78 20 6f 66 20 61 6c 6c 20  st index of all 
25410 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 69  SQL parameters i
25420 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
25430 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
25440 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30 20 69  ement] S, or 0 i
25450 66 20 53 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  f S contains no 
25460 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  SQL parameters..
25470 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
25480 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
25490 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
254a0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
254b0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
254c0 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20 7b 48  ost Parameter {H
254d0 31 33 36 32 30 7d 20 3c 53 37 30 33 30 30 3e 0a  13620} <S70300>.
254e0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
254f0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
25500 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65  nter to the name
25510 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20   of the n-th.** 
25520 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
25530 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
25540 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51  tatement]..** SQ
25550 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
25560 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
25570 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
25580 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
25590 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
255a0 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
255b0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
255c0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
255d0 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
255e0 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
255f0 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
25600 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
25610 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
25620 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
25630 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
25640 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73  e..** Parameters
25650 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
25660 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
25670 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
25680 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64  e no name.** and
25690 20 61 72 65 20 61 6c 73 6f 20 72 65 66 65 72 72   are also referr
256a0 65 64 20 74 6f 20 61 73 20 22 61 6e 6f 6e 79 6d  ed to as "anonym
256b0 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
256c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
256d0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
256e0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
256f0 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20  1, not 0..**.** 
25700 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69  If the value n i
25710 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
25720 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61  r if the n-th pa
25730 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
25740 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
25750 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
25760 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
25770 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
25780 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
25790 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
257a0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
257b0 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
257c0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
257d0 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
257e0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
257f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
25800 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
25810 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
25820 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
25830 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
25840 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
25850 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
25860 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
25870 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
25880 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
25890 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
258a0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 32 31 7d  :.**.** {H13621}
258b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   The [sqlite3_bi
258c0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
258d0 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
258e0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
258f0 20 20 20 20 20 20 61 20 55 54 46 2d 38 20 72 65        a UTF-8 re
25900 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 6e  ndering of the n
25910 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 70  ame of the SQL p
25920 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 20  arameter in.**  
25930 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65          the [pre
25940 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25950 20 53 20 68 61 76 69 6e 67 20 69 6e 64 65 78 20   S having index 
25960 4e 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  N, or.**        
25970 20 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20    NULL if there 
25980 69 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65  is no SQL parame
25990 74 65 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e  ter with index N
259a0 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 20 20   or if the.**   
259b0 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
259c0 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20 69 73   with index N is
259d0 20 61 6e 20 61 6e 6f 6e 79 6d 6f 75 73 20 70 61   an anonymous pa
259e0 72 61 6d 65 74 65 72 20 22 3f 22 2e 0a 2a 2f 0a  rameter "?"..*/.
259f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
25a00 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
25a10 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
25a20 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
25a30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
25a40 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
25a50 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
25a60 4e 61 6d 65 20 7b 48 31 33 36 34 30 7d 20 3c 53  Name {H13640} <S
25a70 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74  70300>.**.** Ret
25a80 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
25a90 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
25aa0 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
25ab0 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20  .  The.** index 
25ac0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
25ad0 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
25ae0 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
25af0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
25b00 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
25b10 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
25b20 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20  ()].  A zero.** 
25b30 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
25b40 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
25b50 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
25b60 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
25b70 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
25b80 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
25b90 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
25ba0 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
25bb0 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
25bc0 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
25bd0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
25be0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
25bf0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
25c00 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
25c10 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
25c20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
25c30 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
25c40 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
25c50 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
25c60 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
25c70 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
25c80 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 34 31 7d 20  .**.** {H13641} 
25c90 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  The [sqlite3_bin
25ca0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
25cb0 78 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  x(S,N)] interfac
25cc0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
25cd0 20 20 20 20 20 20 74 68 65 20 69 6e 64 65 78 20        the index 
25ce0 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  of SQL parameter
25cf0 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
25d00 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
25d10 20 20 20 20 20 20 20 20 20 53 20 77 68 6f 73 65           S whose
25d20 20 6e 61 6d 65 20 6d 61 74 63 68 65 73 20 74 68   name matches th
25d30 65 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 4e  e UTF-8 string N
25d40 2c 20 6f 72 20 30 20 69 66 20 74 68 65 72 65 20  , or 0 if there 
25d50 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  is.**          n
25d60 6f 20 6d 61 74 63 68 2e 0a 2a 2f 0a 69 6e 74 20  o match..*/.int 
25d70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
25d80 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
25d90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
25da0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
25db0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25dc0 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
25dd0 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
25de0 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33  d Statement {H13
25df0 36 36 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  660} <S70300>.**
25e00 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f 20  .** Contrary to 
25e10 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
25e20 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
25e30 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
25e40 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
25e50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
25e60 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
25e70 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
25e80 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 55 73 65 20  tement]..** Use 
25e90 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
25ea0 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
25eb0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
25ec0 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  L..**.** INVARIA
25ed0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36  NTS:.**.** {H136
25ee0 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  61} The [sqlite3
25ef0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
25f00 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
25f10 73 65 74 73 20 61 6c 6c 20 53 51 4c 0a 2a 2a 20  sets all SQL.** 
25f20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74           paramet
25f30 65 72 20 62 69 6e 64 69 6e 67 73 20 69 6e 20 74  er bindings in t
25f40 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
25f50 74 65 6d 65 6e 74 5d 20 53 20 62 61 63 6b 20 74  tement] S back t
25f60 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
25f70 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
25f80 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
25f90 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
25fa0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
25fb0 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
25fc0 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37 31 30  sult Set {H13710
25fd0 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10700>.**.**
25fe0 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62   Return the numb
25ff0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
26000 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
26010 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
26020 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
26030 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f  tement]. This ro
26040 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
26050 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53  if pStmt is an S
26060 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
26070 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65  that does not re
26080 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65  turn data (for e
26090 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
260a0 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  E])..**.** INVAR
260b0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
260c0 33 37 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3711} The [sqlit
260d0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
260e0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
260f0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
26100 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
26110 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
26120 65 73 75 6c 74 20 73 65 74 20 67 65 6e 65 72 61  esult set genera
26130 74 65 64 20 62 79 20 74 68 65 20 5b 70 72 65 70  ted by the [prep
26140 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
26150 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  S,.**          o
26160 72 20 30 20 69 66 20 53 20 64 6f 65 73 20 6e 6f  r 0 if S does no
26170 74 20 67 65 6e 65 72 61 74 65 20 61 20 72 65 73  t generate a res
26180 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20  ult set..*/.int 
26190 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
261a0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
261b0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
261c0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
261d0 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
261e0 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37 32 30  sult Set {H13720
261f0 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10700>.**.**
26200 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
26210 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
26220 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
26230 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
26240 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
26250 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
26260 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54  T] statement.  T
26270 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
26280 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
26290 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
262a0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
262b0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
262c0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
262d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
262e0 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
262f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
26300 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
26310 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
26320 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
26330 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
26340 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26350 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
26360 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43  ments the [SELEC
26370 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 54 68  T] statement. Th
26380 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
26390 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c  er is the.** col
263a0 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65  umn number.  The
263b0 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
263c0 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a   is number 0..**
263d0 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64  .** The returned
263e0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
263f0 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65  is valid until e
26400 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61  ither the [prepa
26410 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
26420 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62  * is destroyed b
26430 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  y [sqlite3_final
26440 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
26450 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
26460 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
26470 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
26480 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
26490 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
264a0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49   column..**.** I
264b0 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
264c0 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
264d0 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
264e0 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
264f0 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
26500 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
26510 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
26520 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
26530 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
26540 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
26550 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
26560 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
26570 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
26580 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
26590 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
265a0 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
265b0 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
265c0 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
265d0 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
265e0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
265f0 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
26600 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
26610 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
26620 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
26630 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
26640 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
26650 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 31  S:.**.** {H13721
26660 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
26670 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
26680 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
26690 5f 6e 61 6d 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20  _name(S,N)].**  
266a0 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
266b0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61  e returns the na
266c0 6d 65 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f  me of the Nth co
266d0 6c 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73  lumn (where 0 is
266e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
266f0 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
26700 29 20 66 6f 72 20 74 68 65 20 72 65 73 75 6c 74  ) for the result
26710 20 73 65 74 20 6f 66 20 74 68 65 0a 2a 2a 20 20   set of the.**  
26720 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
26730 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61  d statement] S a
26740 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
26750 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
26760 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 33 7d  ..**.** {H13723}
26770 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
26780 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
26790 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
267a0 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20  name16(S,N)].** 
267b0 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
267c0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
267d0 61 6d 65 20 6f 66 20 74 68 65 20 4e 74 68 20 63  ame of the Nth c
267e0 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69  olumn (where 0 i
267f0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
26800 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
26810 6e 29 20 66 6f 72 20 74 68 65 20 72 65 73 75 6c  n) for the resul
26820 74 20 73 65 74 20 6f 66 20 74 68 65 0a 2a 2a 20  t set of the.** 
26830 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
26840 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
26850 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  as a zero-termin
26860 61 74 65 64 20 55 54 46 2d 31 36 20 73 74 72 69  ated UTF-16 stri
26870 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ng.**          i
26880 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
26890 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  e order..**.** {
268a0 48 31 33 37 32 34 7d 20 54 68 65 20 5b 73 71 6c  H13724} The [sql
268b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
268c0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
268d0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
268e0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
268f0 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20  terfaces return 
26900 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
26910 66 20 74 68 65 79 20 61 72 65 20 75 6e 61 62 6c  f they are unabl
26920 65 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  e to.**         
26930 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
26940 20 74 6f 20 68 6f 6c 64 20 74 68 65 69 72 20 6e   to hold their n
26950 6f 72 6d 61 6c 20 72 65 74 75 72 6e 20 73 74 72  ormal return str
26960 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ings..**.** {H13
26970 37 32 35 7d 20 49 66 20 74 68 65 20 4e 20 70 61  725} If the N pa
26980 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
26990 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
269a0 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  S,N)] or.**     
269b0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
269c0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  lumn_name16(S,N)
269d0 5d 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  ] is out of rang
269e0 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20  e, then the.**  
269f0 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
26a00 65 73 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c  es return a NULL
26a10 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
26a20 7b 48 31 33 37 32 36 7d 20 54 68 65 20 73 74 72  {H13726} The str
26a30 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
26a40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
26a50 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 61 6e 64 0a  _name(S,N)] and.
26a60 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
26a70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
26a80 31 36 28 53 2c 4e 29 5d 20 61 72 65 20 76 61 6c  16(S,N)] are val
26a90 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  id until the nex
26aa0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  t.**          ca
26ab0 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 72 6f 75  ll to either rou
26ac0 74 69 6e 65 20 77 69 74 68 20 74 68 65 20 73 61  tine with the sa
26ad0 6d 65 20 53 20 61 6e 64 20 4e 20 70 61 72 61 6d  me S and N param
26ae0 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  eters.**        
26af0 20 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69    or until [sqli
26b00 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d  te3_finalize(S)]
26b10 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a   is called..**.*
26b20 2a 20 7b 48 31 33 37 32 37 7d 20 57 68 65 6e 20  * {H13727} When 
26b30 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
26b40 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
26b50 61 74 65 6d 65 6e 74 20 63 6f 6e 74 61 69 6e 73  atement contains
26b60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20  .**          an 
26b70 41 53 20 63 6c 61 75 73 65 2c 20 74 68 65 20 6e  AS clause, the n
26b80 61 6d 65 20 6f 66 20 74 68 61 74 20 63 6f 6c 75  ame of that colu
26b90 6d 6e 20 69 73 20 74 68 65 20 69 64 65 6e 74 69  mn is the identi
26ba0 66 69 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  fier.**         
26bb0 20 74 6f 20 74 68 65 20 72 69 67 68 74 20 6f 66   to the right of
26bc0 20 74 68 65 20 41 53 20 6b 65 79 77 6f 72 64 2e   the AS keyword.
26bd0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
26be0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
26bf0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
26c00 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
26c10 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
26c20 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
26c30 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
26c40 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
26c50 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
26c60 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
26c70 65 73 75 6c 74 20 7b 48 31 33 37 34 30 7d 20 3c  esult {H13740} <
26c80 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S10700>.**.** Th
26c90 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
26ca0 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
26cb0 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63  determine what c
26cc0 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a  olumn of what.**
26cd0 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20   table in which 
26ce0 64 61 74 61 62 61 73 65 20 61 20 72 65 73 75 6c  database a resul
26cf0 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
26d00 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20  statement comes 
26d10 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d  from..** The nam
26d20 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
26d30 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
26d40 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
26d50 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
26d60 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46  r a UTF-8 or UTF
26d70 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65  -16 string.  The
26d80 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
26d90 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
26da0 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
26db0 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
26dc0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
26dd0 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
26de0 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
26df0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
26e00 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
26e10 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65  ..** The returne
26e20 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
26e30 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
26e40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26e50 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
26e60 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
26e70 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
26e80 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
26e90 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
26ea0 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
26eb0 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
26ec0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  ncoding..**.** T
26ed0 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65  he names returne
26ee0 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e  d are the origin
26ef0 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61  al un-aliased na
26f00 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61  mes of the.** da
26f10 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
26f20 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
26f30 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
26f40 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f  ent to the follo
26f50 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 20  wing calls is a 
26f60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26f70 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66  ent]..** These f
26f80 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
26f90 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
26fa0 74 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  t the Nth column
26fb0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
26fc0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
26fd0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
26fe0 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
26ff0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  gument..**.** If
27000 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
27010 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
27020 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
27030 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a  expression or.**
27040 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
27050 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
27060 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
27070 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
27080 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e   return.** NULL.
27090 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20    These routine 
270a0 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
270b0 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
270c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
270d0 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
270e0 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
270f0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
27100 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
27110 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 0a  database, table.
27120 2a 2a 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68  ** and column th
27130 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
27140 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
27150 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
27160 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68   As with all oth
27170 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20  er SQLite APIs, 
27180 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64 20  those postfixed 
27190 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e  with "16" return
271a0 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  .** UTF-16 encod
271b0 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65 20  ed strings, the 
271c0 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
271d0 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 20 7b 45  return UTF-8. {E
271e0 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ND}.**.** These 
271f0 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
27200 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
27210 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
27220 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
27230 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
27240 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
27250 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
27260 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a  ymbol defined..*
27270 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 0a 2a 2a  *.** {A13751}.**
27280 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
27290 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
272a0 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
272b0 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
272c0 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
272d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
272e0 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
272f0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
27300 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
27310 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
27320 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
27330 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 31  S:.**.** {H13741
27340 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
27350 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
27360 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ame(S,N)] interf
27370 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
27380 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
27390 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  he UTF-8 zero-te
273a0 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66  rminated name of
273b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
273c0 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  om which the.** 
273d0 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73           Nth res
273e0 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ult column of th
273f0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
27400 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72  ement] S is extr
27410 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20  acted,.**       
27420 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68     or NULL if th
27430 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
27440 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65  S is a general e
27450 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20  xpression.**    
27460 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62        or if unab
27470 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
27480 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74  emory to store t
27490 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b  he name..**.** {
274a0 48 31 33 37 34 32 7d 20 54 68 65 20 5b 73 71 6c  H13742} The [sql
274b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
274c0 62 61 73 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  base_name16(S,N)
274d0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
274e0 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
274f0 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31         the UTF-1
27500 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
27510 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  der zero-termina
27520 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
27530 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20  database.**     
27540 20 20 20 20 20 66 72 6f 6d 20 77 68 69 63 68 20       from which 
27550 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
27560 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72  olumn of the [pr
27570 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27580 5d 20 53 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ] S is.**       
27590 20 20 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72     extracted, or
275a0 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68   NULL if the Nth
275b0 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
275c0 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73  a general expres
275d0 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  sion.**         
275e0 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
275f0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
27600 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61   to store the na
27610 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34  me..**.** {H1374
27620 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
27630 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
27640 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
27650 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
27660 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
27670 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
27680 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
27690 68 65 20 74 61 62 6c 65 20 66 72 6f 6d 20 77 68  he table from wh
276a0 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ich the.**      
276b0 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63      Nth result c
276c0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72  olumn of the [pr
276d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
276e0 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65 64  ] S is extracted
276f0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
27700 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68   NULL if the Nth
27710 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
27720 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73  a general expres
27730 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  sion.**         
27740 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
27750 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
27760 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61   to store the na
27770 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34  me..**.** {H1374
27780 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
27790 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
277a0 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  e16(S,N)] interf
277b0 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
277c0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
277d0 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  he UTF-16 native
277e0 20 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f   byte order zero
277f0 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65  -terminated name
27800 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
27810 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 77            from w
27820 68 69 63 68 20 74 68 65 20 4e 74 68 20 72 65 73  hich the Nth res
27830 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ult column of th
27840 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
27850 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a 2a 20 20  ement] S is.**  
27860 20 20 20 20 20 20 20 20 65 78 74 72 61 63 74 65          extracte
27870 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
27880 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
27890 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65  S is a general e
278a0 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20  xpression.**    
278b0 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62        or if unab
278c0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
278d0 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74  emory to store t
278e0 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b  he name..**.** {
278f0 48 31 33 37 34 35 7d 20 54 68 65 20 5b 73 71 6c  H13745} The [sql
27900 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
27910 69 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e  in_name(S,N)] in
27920 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27930 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
27940 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72     the UTF-8 zer
27950 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
27960 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
27970 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68  olumn from which
27980 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
27990 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
279a0 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61  mn of the [prepa
279b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
279c0 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a   is extracted,.*
279d0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55  *          or NU
279e0 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f  LL if the Nth co
279f0 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67  lumn of S is a g
27a00 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
27a10 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  n.**          or
27a20 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   if unable to al
27a30 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
27a40 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
27a50 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 36 7d 20  .**.** {H13746} 
27a60 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
27a70 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
27a80 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  6(S,N)] interfac
27a90 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
27aa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
27ab0 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
27ac0 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74  yte order zero-t
27ad0 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
27ae0 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 20  f the table.**  
27af0 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20 66          column f
27b00 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e 74  rom which the Nt
27b10 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
27b20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
27b30 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
27b40 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74  tement] S is ext
27b50 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20  racted, or NULL 
27b60 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
27b70 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  n.**          of
27b80 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20   S is a general 
27b90 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66  expression or if
27ba0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
27bb0 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20  ate memory.**   
27bc0 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20         to store 
27bd0 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  the name..**.** 
27be0 7b 48 31 33 37 34 38 7d 20 54 68 65 20 72 65 74  {H13748} The ret
27bf0 75 72 6e 20 76 61 6c 75 65 73 20 66 72 6f 6d 0a  urn values from.
27c00 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
27c10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
27c20 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75  base_name | colu
27c30 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
27c40 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20  rfaces].**      
27c50 20 20 20 20 61 72 65 20 76 61 6c 69 64 20 66 6f      are valid fo
27c60 72 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  r the lifetime o
27c70 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
27c80 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20  statement].**   
27c90 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69 6c 20         or until 
27ca0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
27cb0 63 68 61 6e 67 65 64 20 62 79 20 61 6e 6f 74 68  changed by anoth
27cc0 65 72 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20  er metadata.**  
27cd0 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
27ce0 65 20 63 61 6c 6c 20 66 6f 72 20 74 68 65 20 73  e call for the s
27cf0 61 6d 65 20 70 72 65 70 61 72 65 64 20 73 74 61  ame prepared sta
27d00 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
27d10 6e 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54  n..**.** ASSUMPT
27d20 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 33  IONS:.**.** {A13
27d30 37 35 31 7d 20 49 66 20 74 77 6f 20 6f 72 20 6d  751} If two or m
27d40 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
27d50 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
27d60 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
27d70 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
27d80 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
27d90 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
27da0 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ces].**         
27db0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
27dc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27dd0 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
27de0 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  lumn.**         
27df0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
27e00 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
27e10 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
27e20 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
27e30 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
27e40 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
27e50 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
27e60 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
27e70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
27e80 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
27e90 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
27ea0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
27eb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
27ec0 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
27ed0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
27ee0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
27ef0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
27f00 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
27f10 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
27f20 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
27f30 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
27f40 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
27f50 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
27f60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
27f70 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
27f80 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
27f90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27fa0 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
27fb0 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
27fc0 75 6c 74 20 7b 48 31 33 37 36 30 7d 20 3c 53 31  ult {H13760} <S1
27fd0 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0700>.**.** The 
27fe0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
27ff0 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
28000 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
28010 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
28020 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  is a [SELECT] st
28030 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
28040 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
28050 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65  e.** returned re
28060 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74  sult set of that
28070 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74   [SELECT] is a t
28080 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
28090 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
280a0 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
280b0 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
280c0 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
280d0 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
280e0 72 65 74 75 72 6e 65 64 2e 20 20 49 66 20 74 68  returned.  If th
280f0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
28100 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69  the result set i
28110 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  s an.** expressi
28120 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20  on or subquery, 
28130 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  then a NULL poin
28140 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
28150 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64  .** The returned
28160 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
28170 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
28180 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72   {END}.**.** For
28190 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20   example, given 
281a0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
281b0 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
281c0 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
281d0 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e  RIANT);.**.** an
281e0 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
281f0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
28200 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
28210 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
28220 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
28230 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
28240 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
28250 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
28260 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72  for the second r
28270 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
28280 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
28290 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
282a0 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
282b0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 0a 2a  column (i==0)..*
282c0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
282d0 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d   dynamic run-tim
282e0 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75  e typing.  So ju
282f0 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
28300 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
28310 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
28320 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
28330 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
28340 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
28350 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
28360 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
28370 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
28380 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
28390 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
283a0 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
283b0 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
283c0 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73  .  Type.** is as
283d0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
283e0 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
283f0 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
28400 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
28410 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
28420 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  alues..**.** INV
28430 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
28440 48 31 33 37 36 31 7d 20 20 41 20 73 75 63 63 65  H13761}  A succe
28450 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
28460 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
28470 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20 72 65 74  cltype(S,N)] ret
28480 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  urns a.**       
28490 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61      zero-termina
284a0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
284b0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
284c0 64 65 63 6c 61 72 65 64 20 64 61 74 61 74 79 70  declared datatyp
284d0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f  e.**           o
284e0 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
284f0 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72 73 20  mn that appears 
28500 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  as the Nth colum
28510 6e 20 28 6e 75 6d 62 65 72 65 64 0a 2a 2a 20 20  n (numbered.**  
28520 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 30 29           from 0)
28530 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
28540 65 74 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  et to the [prepa
28550 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
28560 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 32 7d  ..**.** {H13762}
28570 20 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63    A successful c
28580 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
28590 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
285a0 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20  6(S,N)].**      
285b0 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 7a       returns a z
285c0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
285d0 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
285e0 65 20 6f 72 64 65 72 20 73 74 72 69 6e 67 0a 2a  e order string.*
285f0 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74  *           cont
28600 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63 6c 61  aining the decla
28610 72 65 64 20 64 61 74 61 74 79 70 65 20 6f 66 20  red datatype of 
28620 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
28630 20 74 68 61 74 20 61 70 70 65 61 72 73 0a 2a 2a   that appears.**
28640 20 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68             as th
28650 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75  e Nth column (nu
28660 6d 62 65 72 65 64 20 66 72 6f 6d 20 30 29 20 6f  mbered from 0) o
28670 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
28680 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   to the.**      
28690 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
286a0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a  tatement] S..**.
286b0 2a 2a 20 7b 48 31 33 37 36 33 7d 20 20 49 66 20  ** {H13763}  If 
286c0 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 30  N is less than 0
286d0 20 6f 72 20 4e 20 69 73 20 67 72 65 61 74 65 72   or N is greater
286e0 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
286f0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  o.**           t
28700 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
28710 75 6d 6e 73 20 69 6e 20 74 68 65 20 5b 70 72 65  umns in the [pre
28720 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28730 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   S,.**          
28740 20 6f 72 20 69 66 20 74 68 65 20 4e 74 68 20 63   or if the Nth c
28750 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 6e  olumn of S is an
28760 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
28770 75 62 71 75 65 72 79 20 72 61 74 68 65 72 0a 2a  ubquery rather.*
28780 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61 6e  *           than
28790 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 2c   a table column,
287a0 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20   or if a memory 
287b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
287c0 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  re.**           
287d0 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 65 6e  occurs during en
287e0 63 6f 64 69 6e 67 20 63 6f 6e 76 65 72 73 69 6f  coding conversio
287f0 6e 73 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  ns, then.**     
28800 20 20 20 20 20 20 63 61 6c 6c 73 20 74 6f 20 5b        calls to [
28810 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
28820 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20 6f 72  ecltype(S,N)] or
28830 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
28840 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
28850 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 20 72  cltype16(S,N)] r
28860 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63  eturn NULL..*/.c
28870 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
28880 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
28890 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
288a0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
288b0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
288c0 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
288d0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
288e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
288f0 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51  : Evaluate An SQ
28900 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33  L Statement {H13
28910 32 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a  200} <S10000>.**
28920 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65  .** After a [pre
28930 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28940 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72   has been prepar
28950 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a  ed using either.
28960 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
28970 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
28980 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
28990 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
289a0 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
289b0 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
289c0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
289d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
289e0 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
289f0 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
28a00 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
28a10 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
28a20 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
28a30 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
28a40 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
28a50 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
28a60 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
28a70 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
28a80 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
28a90 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
28aa0 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
28ab0 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72  newer "v2" inter
28ac0 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  face.** [sqlite3
28ad0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
28ae0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
28af0 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
28b00 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
28b10 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71  ** interface [sq
28b20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
28b30 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
28b40 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
28b50 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
28b60 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  ew "v2" interfac
28b70 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
28b80 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
28b90 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
28ba0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
28bb0 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
28bc0 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
28bd0 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65  .**.** In the le
28be0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
28bf0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
28c00 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
28c10 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a  [SQLITE_BUSY],.*
28c20 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  * [SQLITE_DONE],
28c30 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b   [SQLITE_ROW], [
28c40 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f  SQLITE_ERROR], o
28c50 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
28c60 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22  ]..** With the "
28c70 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
28c80 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
28c90 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
28ca0 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
28cb0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
28cc0 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
28cd0 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53  s well..**.** [S
28ce0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
28cf0 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
28d00 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
28d10 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
28d20 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
28d30 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
28d40 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
28d50 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
28d60 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a   is a [COMMIT].*
28d70 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
28d80 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
28d90 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
28da0 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
28db0 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
28dc0 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
28dd0 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
28de0 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63  [COMMIT] and occ
28df0 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20  urs within a.** 
28e00 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
28e10 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68  tion then you sh
28e20 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68  ould rollback th
28e30 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
28e40 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69  fore.** continui
28e50 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ng..**.** [SQLIT
28e60 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
28e70 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
28e80 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
28e90 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
28ea0 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
28eb0 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
28ec0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
28ed0 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
28ee0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
28ef0 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
28f00 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
28f10 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
28f20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
28f30 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
28f40 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
28f50 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
28f60 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  QL statement bei
28f70 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75  ng executed retu
28f80 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68  rns any data, th
28f90 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a  en [SQLITE_ROW].
28fa0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65  ** is returned e
28fb0 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72  ach time a new r
28fc0 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65  ow of data is re
28fd0 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69  ady for processi
28fe0 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ng by the.** cal
28ff0 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ler. The values 
29000 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20  may be accessed 
29010 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d  using the [colum
29020 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
29030 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
29040 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
29050 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
29060 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
29070 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b  of data..**.** [
29080 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
29090 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
290a0 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
290b0 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
290c0 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
290d0 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
290e0 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
290f0 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
29100 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
29110 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
29120 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
29130 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
29140 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
29150 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 6c 65  ..** With the le
29160 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
29170 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
29180 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
29190 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
291a0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
291b0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
291c0 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
291d0 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
291e0 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
291f0 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
29200 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
29210 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
29220 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
29230 20 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e    In the "v2" in
29240 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
29250 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
29260 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
29270 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
29280 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
29290 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
292a0 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
292b0 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
292c0 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
292d0 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
292e0 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
292f0 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
29300 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29310 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
29320 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
29330 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
29340 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
29350 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20  one that had.** 
29360 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
29370 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
29380 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
29390 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
293a0 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
293b0 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
293c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
293d0 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
293e0 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
293f0 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
29400 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
29410 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e   time..**.** <b>
29420 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
29430 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
29440 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
29450 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
29460 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
29470 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
29480 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
29490 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
294a0 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
294b0 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
294c0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
294d0 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
294e0 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
294f0 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
29500 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
29510 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
29520 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
29530 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
29540 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
29550 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
29560 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
29570 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
29580 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
29590 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
295a0 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
295b0 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
295c0 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
295d0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
295e0 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
295f0 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
29600 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
29610 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
29620 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
29630 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29640 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
29650 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
29660 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
29670 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
29680 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
29690 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20   interfaces,.** 
296a0 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70  then the more sp
296b0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
296c0 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
296d0 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
296e0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
296f0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
29700 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
29710 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
29720 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
29730 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 32 30 32 7d  :.**.** {H13202}
29740 20 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72    If the [prepar
29750 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
29760 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  is ready to be r
29770 75 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  un, then.**     
29780 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
29790 74 65 70 28 53 29 5d 20 61 64 76 61 6e 63 65 73  tep(S)] advances
297a0 20 74 68 61 74 20 70 72 65 70 61 72 65 64 20 73   that prepared s
297b0 74 61 74 65 6d 65 6e 74 20 75 6e 74 69 6c 0a 2a  tatement until.*
297c0 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f 6d 70  *           comp
297d0 6c 65 74 69 6f 6e 20 6f 72 20 75 6e 74 69 6c 20  letion or until 
297e0 69 74 20 69 73 20 72 65 61 64 79 20 74 6f 20 72  it is ready to r
297f0 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f  eturn another ro
29800 77 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  w of the.**     
29810 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74        result set
29820 2c 20 6f 72 20 75 6e 74 69 6c 20 61 6e 20 5b 73  , or until an [s
29830 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
29840 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 0a 2a 2a   | interrupt].**
29850 20 20 20 20 20 20 20 20 20 20 20 6f 72 20 61 20             or a 
29860 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 6f  run-time error o
29870 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ccurs..**.** {H1
29880 35 33 30 34 7d 20 20 57 68 65 6e 20 61 20 63 61  5304}  When a ca
29890 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
298a0 74 65 70 28 53 29 5d 20 63 61 75 73 65 73 20 74  tep(S)] causes t
298b0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
298c0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20  tement].**      
298d0 20 20 20 20 20 53 20 74 6f 20 72 75 6e 20 74 6f       S to run to
298e0 20 63 6f 6d 70 6c 65 74 69 6f 6e 2c 20 74 68 65   completion, the
298f0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
29900 73 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  s [SQLITE_DONE].
29910 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 36 7d 20  .**.** {H15306} 
29920 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20   When a call to 
29930 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
29940 5d 20 73 74 6f 70 73 20 62 65 63 61 75 73 65 20  ] stops because 
29950 69 74 20 69 73 20 72 65 61 64 79 20 74 6f 0a 2a  it is ready to.*
29960 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75  *           retu
29970 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f  rn another row o
29980 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
29990 2c 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51  , it returns [SQ
299a0 4c 49 54 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a  LITE_ROW]..**.**
299b0 20 7b 48 31 35 33 30 38 7d 20 20 49 66 20 61 20   {H15308}  If a 
299c0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
299d0 5f 73 74 65 70 28 53 29 5d 20 65 6e 63 6f 75 6e  _step(S)] encoun
299e0 74 65 72 73 20 61 6e 0a 2a 2a 20 20 20 20 20 20  ters an.**      
299f0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 69 6e       [sqlite3_in
29a00 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72  terrupt | interr
29a10 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69  upt] or a run-ti
29a20 6d 65 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20  me error,.**    
29a30 20 20 20 20 20 20 20 69 74 20 72 65 74 75 72 6e         it return
29a40 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
29a50 20 65 72 72 6f 72 20 63 6f 64 65 20 74 68 61 74   error code that
29a60 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 0a 2a   is not one of.*
29a70 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  *           [SQL
29a80 49 54 45 5f 4f 4b 5d 2c 20 5b 53 51 4c 49 54 45  ITE_OK], [SQLITE
29a90 5f 52 4f 57 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  _ROW], or [SQLIT
29aa0 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  E_DONE]..**.** {
29ab0 48 31 35 33 31 30 7d 20 20 49 66 20 61 6e 20 5b  H15310}  If an [
29ac0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
29ad0 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 20 6f  t | interrupt] o
29ae0 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  r a run-time err
29af0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  or.**           
29b00 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 61 20  occurs during a 
29b10 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
29b20 5f 73 74 65 70 28 53 29 5d 0a 2a 2a 20 20 20 20  _step(S)].**    
29b30 20 20 20 20 20 20 20 66 6f 72 20 61 20 5b 70 72         for a [pr
29b40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29b50 5d 20 53 20 63 72 65 61 74 65 64 20 75 73 69 6e  ] S created usin
29b60 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6c  g.**           l
29b70 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 73  egacy interfaces
29b80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29b90 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  e()] or.**      
29ba0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72       [sqlite3_pr
29bb0 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e  epare16()], then
29bc0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   the function re
29bd0 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
29be0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
29bf0 45 5f 45 52 52 4f 52 5d 2c 20 5b 53 51 4c 49 54  E_ERROR], [SQLIT
29c00 45 5f 42 55 53 59 5d 2c 20 6f 72 20 5b 53 51 4c  E_BUSY], or [SQL
29c10 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2f 0a  ITE_MISUSE]..*/.
29c20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
29c30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
29c40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29c50 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
29c60 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
29c70 73 65 74 20 7b 48 31 33 37 37 30 7d 20 3c 53 31  set {H13770} <S1
29c80 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75  0700>.**.** Retu
29c90 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
29ca0 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20  f values in the 
29cb0 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
29cc0 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a  he result set..*
29cd0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
29ce0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 37 31 7d 20  .**.** {H13771} 
29cf0 20 41 66 74 65 72 20 61 20 63 61 6c 6c 20 74 6f   After a call to
29d00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
29d10 29 5d 20 74 68 61 74 20 72 65 74 75 72 6e 73 20  )] that returns 
29d20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 0a 2a 2a  [SQLITE_ROW],.**
29d30 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b             the [
29d40 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
29d50 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e 65 20 77  nt(S)] routine w
29d60 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 73  ill return the s
29d70 61 6d 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20  ame value.**    
29d80 20 20 20 20 20 20 20 61 73 20 74 68 65 20 5b 73         as the [s
29d90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
29da0 75 6e 74 28 53 29 5d 20 66 75 6e 63 74 69 6f 6e  unt(S)] function
29db0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 37 32 7d  ..**.** {H13772}
29dc0 20 20 41 66 74 65 72 20 5b 73 71 6c 69 74 65 33    After [sqlite3
29dd0 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 72 65  _step(S)] has re
29de0 74 75 72 6e 65 64 20 61 6e 79 20 76 61 6c 75 65  turned any value
29df0 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20   other than.**  
29e00 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
29e10 5f 52 4f 57 5d 20 6f 72 20 62 65 66 6f 72 65 20  _ROW] or before 
29e20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
29e30 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
29e40 64 20 6f 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  d on the.**     
29e50 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
29e60 73 74 61 74 65 6d 65 6e 74 5d 20 66 6f 72 20 74  statement] for t
29e70 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 69  he first time si
29e80 6e 63 65 20 69 74 20 77 61 73 0a 2a 2a 20 20 20  nce it was.**   
29e90 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
29ea0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
29eb0 72 65 64 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  red] or [sqlite3
29ec0 5f 72 65 73 65 74 20 7c 20 72 65 73 65 74 5d 2c  _reset | reset],
29ed0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
29ee0 65 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  e [sqlite3_data_
29ef0 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e  count(S)] routin
29f00 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  e returns zero..
29f10 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
29f20 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
29f30 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
29f40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29f50 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
29f60 61 74 79 70 65 73 20 7b 48 31 30 32 36 35 7d 20  atypes {H10265} 
29f70 3c 53 31 30 31 31 30 3e 3c 53 31 30 31 32 30 3e  <S10110><S10120>
29f80 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
29f90 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
29fa0 7b 48 31 30 32 36 36 7d 20 45 76 65 72 79 20 76  {H10266} Every v
29fb0 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
29fc0 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
29fd0 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
29fe0 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
29ff0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
2a000 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
2a010 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
2a020 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
2a030 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
2a040 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
2a050 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
2a060 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d  L.** </ul> {END}
2a070 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
2a080 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
2a090 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
2a0a0 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
2a0b0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
2a0c0 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
2a0d0 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
2a0e0 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
2a0f0 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
2a100 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
2a110 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
2a120 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
2a130 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
2a140 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2a150 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
2a160 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
2a170 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20  e SQLITE3_TEXT, 
2a180 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45  not.** SQLITE_TE
2a190 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  XT..*/.#define S
2a1a0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31  QLITE_INTEGER  1
2a1b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a1c0 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69  FLOAT    2.#defi
2a1d0 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20  ne SQLITE_BLOB  
2a1e0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
2a1f0 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23  ITE_NULL     5.#
2a200 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  ifdef SQLITE_TEX
2a210 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  T.# undef SQLITE
2a220 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65  _TEXT.#else.# de
2a230 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54  fine SQLITE_TEXT
2a240 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64       3.#endif.#d
2a250 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45  efine SQLITE3_TE
2a260 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20  XT     3../*.** 
2a270 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
2a280 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
2a290 75 65 72 79 20 7b 48 31 33 38 30 30 7d 20 3c 53  uery {H13800} <S
2a2a0 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  10700>.** KEYWOR
2a2b0 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65  DS: {column acce
2a2c0 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  ss functions}.**
2a2d0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2a2e0 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73  es form the "res
2a2f0 75 6c 74 20 73 65 74 20 71 75 65 72 79 22 20 69  ult set query" i
2a300 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
2a310 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2a320 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2a330 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
2a340 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
2a350 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
2a360 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
2a370 20 20 49 6e 20 65 76 65 72 79 20 63 61 73 65 20    In every case 
2a380 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2a390 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a  nt is a pointer.
2a3a0 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  ** to the [prepa
2a3b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2a3c0 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61  hat is being eva
2a3d0 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c  luated (the [sql
2a3e0 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74  ite3_stmt*].** t
2a3f0 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
2a400 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70   from [sqlite3_p
2a410 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2a420 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
2a430 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  nts).** and the 
2a440 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2a450 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
2a460 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77  the column for w
2a470 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  hich information
2a480 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
2a490 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65 66  turned.  The lef
2a4a0 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  tmost column of 
2a4b0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68  the result set h
2a4c0 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a  as the index 0..
2a4d0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
2a4e0 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
2a4f0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f  not currently po
2a500 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72  int to a valid r
2a510 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  ow, or if the.**
2a520 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
2a530 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
2a540 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
2a550 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65  efined..** These
2a560 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e   routines may on
2a570 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
2a580 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
2a590 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
2a5a0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2a5b0 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  s returned [SQLI
2a5c0 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74  TE_ROW] and neit
2a5d0 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
2a5e0 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71  reset()] nor [sq
2a5f0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2a600 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  ] have been call
2a610 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ed subsequently.
2a620 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
2a630 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2a640 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
2a650 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2a660 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
2a670 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
2a680 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
2a690 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
2a6a0 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
2a6b0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
2a6c0 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
2a6d0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2a6e0 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
2a6f0 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
2a700 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2a710 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2a720 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
2a730 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
2a740 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
2a750 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
2a760 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
2a770 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
2a780 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2a790 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
2a7a0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2a7b0 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
2a7c0 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
2a7d0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
2a7e0 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d  | datatype code]
2a7f0 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c   for the initial
2a800 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66   data type.** of
2a810 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
2a820 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65  mn.  The returne
2a830 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
2a840 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
2a850 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
2a860 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
2a870 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
2a880 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
2a890 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
2a8a0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
2a8b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a8c0 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
2a8d0 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
2a8e0 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
2a8f0 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
2a900 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
2a910 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
2a920 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
2a930 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
2a940 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2a950 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2a960 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
2a970 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
2a980 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
2a990 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
2a9a0 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
2a9b0 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
2a9c0 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
2a9d0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
2a9e0 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20  * If the result 
2a9f0 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
2aa00 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  -8 string then t
2aa10 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2aa20 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75  n_bytes().** rou
2aa30 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2aa40 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2aa50 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
2aa60 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74   string..** If t
2aa70 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
2aa80 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
2aa90 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2aaa0 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
2aab0 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
2aac0 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
2aad0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
2aae0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
2aaf0 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
2ab00 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
2ab10 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
2ab20 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2ab30 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
2ab40 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
2ab50 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
2ab60 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
2ab70 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2ab80 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2ab90 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2aba0 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76  string..** The v
2abb0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f  alue returned do
2abc0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  es not include t
2abd0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
2abe0 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  or at the end.**
2abf0 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
2ac00 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68   For clarity: th
2ac10 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
2ac20 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
2ac30 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
2ac40 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
2ac50 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
2ac60 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74  acters..**.** St
2ac70 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
2ac80 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2ac90 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
2aca0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2acb0 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
2acc0 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
2acd0 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d  always zero term
2ace0 69 6e 61 74 65 64 2e 20 20 54 68 65 20 72 65 74  inated.  The ret
2acf0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
2ad00 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
2ad10 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
2ad20 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
2ad30 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a  s an arbitrary.*
2ad40 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69  * pointer, possi
2ad50 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20  bly even a NULL 
2ad60 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
2ad70 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2ad80 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75 74  n_bytes16() rout
2ad90 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
2ada0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2adb0 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20  _bytes().** but 
2adc0 6c 65 61 76 65 73 20 74 68 65 20 72 65 73 75 6c  leaves the resul
2add0 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e  t in UTF-16 in n
2ade0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2adf0 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d   instead of UTF-
2ae00 38 2e 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74  8..** The zero t
2ae10 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74  erminator is not
2ae20 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69   included in thi
2ae30 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  s count..**.** T
2ae40 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
2ae50 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2ae60 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2ae70 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
2ae80 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2ae90 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
2aea0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2aeb0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2aec0 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
2aed0 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
2aee0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
2aef0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
2af00 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
2af10 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
2af20 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2af30 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
2af40 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
2af50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2af60 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
2af70 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
2af80 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
2af90 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
2afa0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2afb0 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
2afc0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
2afd0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
2afe0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
2aff0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2b000 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
2b010 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2b020 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
2b030 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
2b040 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
2b050 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ate.  For.** exa
2b060 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74  mple, if the int
2b070 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
2b080 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e  tion is FLOAT an
2b090 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a  d a text result.
2b0a0 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c  ** is requested,
2b0b0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2b0c0 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  tf()] is used in
2b0d0 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66  ternally to perf
2b0e0 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65  orm the.** conve
2b0f0 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61  rsion automatica
2b100 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77  lly.  The follow
2b110 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
2b120 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
2b130 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70  s.** that are ap
2b140 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
2b150 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
2b160 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
2b170 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
2b180 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
2b190 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
2b1a0 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
2b1b0 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
2b1c0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2b1d0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2b1e0 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
2b1f0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2b200 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2b210 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2b220 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
2b230 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
2b240 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
2b250 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  ult is NULL poin
2b260 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
2b270 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
2b280 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73  BLOB    <td> Res
2b290 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  ult is NULL poin
2b2a0 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
2b2b0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46  INTEGER  <td>  F
2b2c0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
2b2d0 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65  vert from intege
2b2e0 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74  r to float.** <t
2b2f0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2b300 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2b310 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
2b320 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67  ing of the integ
2b330 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
2b340 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42  NTEGER  <td>   B
2b350 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
2b360 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58   as INTEGER->TEX
2b370 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  T.** <tr><td>  F
2b380 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOAT   <td> INTE
2b390 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
2b3a0 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f  rt from float to
2b3b0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
2b3c0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
2b3d0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2b3e0 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
2b3f0 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a  g of the float.*
2b400 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2b410 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  T   <td>   BLOB 
2b420 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
2b430 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c  FLOAT->TEXT.** <
2b440 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
2b450 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2b460 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a  <td> Use atoi().
2b470 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
2b480 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  T    <td>  FLOAT
2b490 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f      <td> Use ato
2b4a0 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
2b4b0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20   TEXT    <td>   
2b4c0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20  BLOB    <td> No 
2b4d0 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74  change.** <tr><t
2b4e0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2b4f0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2b500 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20  Convert to TEXT 
2b510 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a  then use atoi().
2b520 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2b530 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
2b540 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
2b550 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
2b560 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e  e atof().** <tr>
2b570 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2b580 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2b590 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72  > Add a zero ter
2b5a0 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65  minator if neede
2b5b0 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  d.** </table>.**
2b5c0 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a   </blockquote>.*
2b5d0 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61  *.** The table a
2b5e0 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72  bove makes refer
2b5f0 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64  ence to standard
2b600 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74   C library funct
2b610 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61  ions atoi().** a
2b620 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69  nd atof().  SQLi
2b630 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c  te does not real
2b640 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e  ly use these fun
2b650 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20  ctions.  It has 
2b660 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76  its.** own equiv
2b670 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72  alent internal r
2b680 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74  outines.  The at
2b690 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20  oi() and atof() 
2b6a0 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65  names are.** use
2b6b0 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66  d in the table f
2b6c0 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62  or brevity and b
2b6d0 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20  ecause they are 
2b6e0 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74  familiar to most
2b6f0 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72  .** C programmer
2b700 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
2b710 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
2b720 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
2b730 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2b740 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
2b750 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2b760 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
2b770 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2b780 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
2b790 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2b7a0 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
2b7b0 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79  validated..** Ty
2b7c0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
2b7d0 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
2b7e0 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
2b7f0 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
2b800 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
2b810 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2b820 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2b830 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
2b840 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2b850 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
2b860 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2b870 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
2b880 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
2b890 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
2b8a0 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
2b8b0 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
2b8c0 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
2b8d0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
2b8e0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
2b8f0 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
2b900 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2b910 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
2b920 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b930 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
2b940 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
2b950 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
2b960 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
2b970 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
2b980 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2b990 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
2b9a0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
2b9b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2b9c0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2b9d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2b9e0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
2b9f0 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
2ba00 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
2ba10 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
2ba20 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
2ba30 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65  * Conversions be
2ba40 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61  tween UTF-16be a
2ba50 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20  nd UTF-16le are 
2ba60 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70  always done in p
2ba70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e  lace and do.** n
2ba80 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20  ot invalidate a 
2ba90 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74  prior pointer, t
2baa0 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
2bab0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2bac0 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  he buffer.** tha
2bad0 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e  t the prior poin
2bae0 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 77 69  ter points to wi
2baf0 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64  ll have been mod
2bb00 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69  ified.  Other ki
2bb10 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72  nds.** of conver
2bb20 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e  sion are done in
2bb30 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69   place when it i
2bb40 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20  s possible, but 
2bb50 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a  sometimes they.*
2bb60 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62  * are not possib
2bb70 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20  le and in those 
2bb80 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e  cases prior poin
2bb90 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64  ters are invalid
2bba0 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
2bbb0 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65  safest and easie
2bbc0 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70  st to remember p
2bbd0 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
2bbe0 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
2bbf0 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
2bc00 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
2bc10 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2bc20 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
2bc30 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
2bc40 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2bc50 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
2bc60 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
2bc70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2bc80 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
2bc90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2bca0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
2bcb0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2bcc0 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
2bcd0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2bce0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
2bcf0 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
2bd00 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
2bd10 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
2bd20 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
2bd30 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c  n_text(),.** sql
2bd40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2bd50 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  (), or sqlite3_c
2bd60 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
2bd70 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
2bd80 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f  e result.** into
2bd90 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72   the desired for
2bda0 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
2bdb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bdc0 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71  bytes() or.** sq
2bdd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2bde0 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74  es16() to find t
2bdf0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
2be00 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
2be10 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73  ix calls.** to s
2be20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2be30 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2be40 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
2be50 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  th calls to.** s
2be60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2be70 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20  tes16(), and do 
2be80 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  not mix calls to
2be90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bea0 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68  text16().** with
2beb0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2bec0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2bed0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ..**.** The poin
2bee0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
2bef0 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
2bf00 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
2bf10 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
2bf20 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
2bf30 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
2bf40 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2bf50 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
2bf60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2bf70 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
2bf80 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 73  d.  The memory s
2bf90 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
2bfa0 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
2bfb0 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20   BLOBs is freed 
2bfc0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2bfd0 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61  Do <b>not</b> pa
2bfe0 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20  ss the pointers 
2bff0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c  returned.** [sql
2c000 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2c010 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
2c020 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
2c030 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
2c040 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
2c050 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61  ** If a memory a
2c060 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
2c070 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
2c080 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
2c090 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
2c0a0 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
2c0b0 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
2c0c0 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
2c0d0 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
2c0e0 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
2c0f0 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
2c100 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
2c110 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
2c120 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
2c130 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
2c140 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
2c150 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
2c160 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
2c170 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
2c180 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  NTS:.**.** {H138
2c190 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  03} The [sqlite3
2c1a0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e  _column_blob(S,N
2c1b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2c1c0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
2c1d0 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
2c1e0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
2c1f0 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
2c200 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
2c210 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61        the [prepa
2c220 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2c230 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 61 6e 64   into a BLOB and
2c240 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 61 0a   then returns a.
2c250 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e  **          poin
2c260 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 65  ter to the conve
2c270 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  rted value..**.*
2c280 2a 20 7b 48 31 33 38 30 36 7d 20 54 68 65 20 5b  * {H13806} The [
2c290 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c2a0 79 74 65 73 28 53 2c 4e 29 5d 20 69 6e 74 65 72  ytes(S,N)] inter
2c2b0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2c2c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
2c2d0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2c2e0 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
2c2f0 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66  ng (exclusive of
2c300 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2c310 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2c320 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20   on the string) 
2c330 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
2c340 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
2c350 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74       most recent
2c360 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2c370 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c  3_column_blob(S,
2c380 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  N)] or.**       
2c390 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
2c3a0 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 2e 0a 2a  mn_text(S,N)]..*
2c3b0 2a 0a 2a 2a 20 7b 48 31 33 38 30 39 7d 20 54 68  *.** {H13809} Th
2c3c0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2c3d0 6e 5f 62 79 74 65 73 31 36 28 53 2c 4e 29 5d 20  n_bytes16(S,N)] 
2c3e0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2c3f0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2c400 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65    number of byte
2c410 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20  s in the string 
2c420 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68  (exclusive of th
2c430 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  e.**          ze
2c440 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e  ro terminator on
2c450 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61   the string) tha
2c460 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62  t was returned b
2c470 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  y the.**        
2c480 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61    most recent ca
2c490 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2c4a0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e  olumn_text16(S,N
2c4b0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31  )]..**.** {H1381
2c4c0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
2c4d0 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 53 2c  column_double(S,
2c4e0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
2c4f0 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2c500 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
2c510 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
2c520 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2c530 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a  lt set for the.*
2c540 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2c550 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2c560 53 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e  S into a floatin
2c570 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e  g point value an
2c580 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
2c590 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  turns a copy of 
2c5a0 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  that value..**.*
2c5b0 2a 20 7b 48 31 33 38 31 35 7d 20 54 68 65 20 5b  * {H13815} The [
2c5c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2c5d0 6e 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  nt(S,N)] interfa
2c5e0 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2c5f0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
2c600 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
2c610 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
2c620 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20   result set for 
2c630 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2c640 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c650 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34  ent] S into a 64
2c660 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2c670 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ger and.**      
2c680 20 20 20 20 72 65 74 75 72 6e 73 20 74 68 65 20      returns the 
2c690 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f 66  lower 32 bits of
2c6a0 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a   that integer..*
2c6b0 2a 0a 2a 2a 20 7b 48 31 33 38 31 38 7d 20 54 68  *.** {H13818} Th
2c6c0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2c6d0 6e 5f 69 6e 74 36 34 28 53 2c 4e 29 5d 20 69 6e  n_int64(S,N)] in
2c6e0 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
2c6f0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2c700 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
2c710 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
2c720 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2c730 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
2c740 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
2c750 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
2c760 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64   a 64-bit signed
2c770 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20   integer and.** 
2c780 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
2c790 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20   a copy of that 
2c7a0 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  integer..**.** {
2c7b0 48 31 33 38 32 31 7d 20 54 68 65 20 5b 73 71 6c  H13821} The [sql
2c7c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c7d0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
2c7e0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2c7f0 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f            Nth co
2c800 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
2c810 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
2c820 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a  esult set for.**
2c830 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70            the [p
2c840 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c850 74 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f  t] S into a zero
2c860 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
2c870 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  8.**          st
2c880 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2c890 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2c8a0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  at string..**.**
2c8b0 20 7b 48 31 33 38 32 34 7d 20 54 68 65 20 5b 73   {H13824} The [s
2c8c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c8d0 78 74 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  xt16(S,N)] inter
2c8e0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2c8f0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
2c900 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
2c910 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
2c920 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
2c930 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
2c940 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
2c950 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
2c960 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2c970 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20  2-byte.**       
2c980 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31     aligned UTF-1
2c990 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
2c9a0 64 65 72 20 73 74 72 69 6e 67 20 61 6e 64 20 72  der string and r
2c9b0 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
2c9c0 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20     a pointer to 
2c9d0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
2c9e0 2a 2a 20 7b 48 31 33 38 32 37 7d 20 54 68 65 20  ** {H13827} The 
2c9f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2ca00 74 79 70 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  type(S,N)] inter
2ca10 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
2ca20 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20           one of 
2ca30 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b  [SQLITE_NULL], [
2ca40 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
2ca50 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
2ca60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
2ca70 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b  LITE_TEXT], or [
2ca80 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20  SQLITE_BLOB] as 
2ca90 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a  appropriate for.
2caa0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2cab0 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
2cac0 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
2cad0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2cae0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
2caf0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2cb00 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a  atement] S..**.*
2cb10 2a 20 7b 48 31 33 38 33 30 7d 20 54 68 65 20 5b  * {H13830} The [
2cb20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2cb30 61 6c 75 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  alue(S,N)] inter
2cb40 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 0a 2a  face returns a.*
2cb50 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
2cb60 65 72 20 74 6f 20 61 6e 20 5b 75 6e 70 72 6f 74  er to an [unprot
2cb70 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2cb80 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 20  lue] object for 
2cb90 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2cba0 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
2cbb0 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
2cbc0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2cbd0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
2cbe0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2cbf0 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 63  atement] S..*/.c
2cc00 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2cc10 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73  e3_column_blob(s
2cc20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2cc30 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
2cc40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2cc50 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
2cc60 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
2cc70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2cc80 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73  ytes16(sqlite3_s
2cc90 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2cca0 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
2ccb0 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71  column_double(sq
2ccc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2ccd0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
2cce0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73  te3_column_int(s
2ccf0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2cd00 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
2cd10 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63  _int64 sqlite3_c
2cd20 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69  olumn_int64(sqli
2cd30 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2cd40 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  Col);.const unsi
2cd50 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
2cd60 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73  e3_column_text(s
2cd70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2cd80 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76  t iCol);.const v
2cd90 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2cda0 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74  umn_text16(sqlit
2cdb0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2cdc0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2cdd0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c  _column_type(sql
2cde0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2cdf0 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76  iCol);.sqlite3_v
2ce00 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f  alue *sqlite3_co
2ce10 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74  lumn_value(sqlit
2ce20 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2ce30 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ol);../*.** CAPI
2ce40 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20  3REF: Destroy A 
2ce50 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2ce60 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 30  nt Object {H1330
2ce70 30 7d 20 3c 53 37 30 33 30 30 3e 3c 53 33 30 31  0} <S70300><S301
2ce80 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
2ce90 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2cea0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
2ceb0 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
2cec0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ced0 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ent]..** If the 
2cee0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 65 78  statement was ex
2cef0 65 63 75 74 65 64 20 73 75 63 63 65 73 73 66 75  ecuted successfu
2cf00 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 75  lly or not execu
2cf10 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e  ted at all, then
2cf20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73  .** SQLITE_OK is
2cf30 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20 65 78   returned. If ex
2cf40 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  ecution of the s
2cf50 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20  tatement failed 
2cf60 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  then an.** [erro
2cf70 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65  r code] or [exte
2cf80 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
2cf90 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2cfa0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
2cfb0 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
2cfc0 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
2cfd0 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
2cfe0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   of the.** [prep
2cff0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2d000 20 20 49 66 20 74 68 65 20 76 69 72 74 75 61 6c    If the virtual
2d010 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74   machine has not
2d020 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78  .** completed ex
2d030 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69  ecution when thi
2d040 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  s routine is cal
2d050 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b  led, that is lik
2d060 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e  e.** encounterin
2d070 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e  g an error or an
2d080 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
2d090 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d  upt | interrupt]
2d0a0 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20  ..** Incomplete 
2d0b0 75 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 72  updates may be r
2d0c0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74  olled back and t
2d0d0 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63  ransactions canc
2d0e0 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69  eled,.** dependi
2d0f0 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d  ng on the circum
2d100 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65  stances, and the
2d110 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
2d120 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62   returned will b
2d130 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  e [SQLITE_ABORT]
2d140 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2d150 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30  TS:.**.** {H1130
2d160 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
2d170 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 6e 74  finalize(S)] int
2d180 65 72 66 61 63 65 20 64 65 73 74 72 6f 79 73 20  erface destroys 
2d190 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2d1a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d1b0 65 6e 74 5d 20 53 20 61 6e 64 20 72 65 6c 65 61  ent] S and relea
2d1c0 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  ses all.**      
2d1d0 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20 66      memory and f
2d1e0 69 6c 65 20 72 65 73 6f 75 72 63 65 73 20 68 65  ile resources he
2d1f0 6c 64 20 62 79 20 74 68 61 74 20 6f 62 6a 65 63  ld by that objec
2d200 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 34  t..**.** {H11304
2d210 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  } If the most re
2d220 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2d230 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2d240 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
2d250 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
2d260 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e  tement] S return
2d270 65 64 20 61 6e 20 65 72 72 6f 72 2c 0a 2a 2a 20  ed an error,.** 
2d280 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73           then [s
2d290 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2d2a0 53 29 5d 20 72 65 74 75 72 6e 73 20 74 68 61 74  S)] returns that
2d2b0 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a 2a 2f 0a   same error..*/.
2d2c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
2d2d0 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
2d2e0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2d2f0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2d300 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
2d310 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48  tement Object {H
2d320 31 33 33 33 30 7d 20 3c 53 37 30 33 30 30 3e 0a  13330} <S70300>.
2d330 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2d340 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69  3_reset() functi
2d350 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
2d360 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65  reset a [prepare
2d370 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2d380 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69  object back to i
2d390 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
2d3a0 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65  , ready to be re
2d3b0 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e  -executed..** An
2d3c0 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
2d3d0 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68  variables that h
2d3e0 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20  ad values bound 
2d3f0 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a  to them using.**
2d400 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
2d410 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
2d420 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20  3_bind_*() API] 
2d430 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c  retain their val
2d440 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c  ues..** Use [sql
2d450 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
2d460 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20  ngs()] to reset 
2d470 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a  the bindings..**
2d480 0a 2a 2a 20 7b 48 31 31 33 33 32 7d 20 54 68 65  .** {H11332} The
2d490 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2d4a0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
2d4b0 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
2d4c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
2d4d0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 61 63 6b  **          back
2d4e0 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   to the beginnin
2d4f0 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d  g of its program
2d500 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 34 7d  ..**.** {H11334}
2d510 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   If the most rec
2d520 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
2d530 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
2d540 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
2d550 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
2d560 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
2d570 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f  d [SQLITE_ROW] o
2d580 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  r [SQLITE_DONE],
2d590 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
2d5a0 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  if [sqlite3_step
2d5b0 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62  (S)] has never b
2d5c0 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65  efore been calle
2d5d0 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20  d on S,.**      
2d5e0 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65      then [sqlite
2d5f0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
2d600 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
2d610 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 36 7d 20  .**.** {H11336} 
2d620 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2d630 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2d640 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
2d650 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2d660 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d670 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65  ment] S indicate
2d680 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e  d an error, then
2d690 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2d6a0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2d6b0 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
2d6c0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
2d6d0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33  de]..**.** {H113
2d6e0 33 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  38} The [sqlite3
2d6f0 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
2d700 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68  face does not ch
2d710 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a  ange the values.
2d720 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61  **          of a
2d730 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
2d740 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
2d750 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
2d760 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
2d770 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
2d780 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
2d790 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2d7a0 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
2d7b0 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
2d7c0 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36  L Functions {H16
2d7d0 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  100} <S20200>.**
2d7e0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
2d7f0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
2d800 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f  utines}.** KEYWO
2d810 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
2d820 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2d830 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f  nction}.** KEYWO
2d840 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
2d850 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2d860 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54  nctions}.**.** T
2d870 68 65 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f  hese two functio
2d880 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79  ns (collectively
2d890 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74   known as "funct
2d8a0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
2d8b0 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75  tines").** are u
2d8c0 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66  sed to add SQL f
2d8d0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
2d8e0 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64  egates or to red
2d8f0 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69  efine the behavi
2d900 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e  or.** of existin
2d910 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  g SQL functions 
2d920 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  or aggregates.  
2d930 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65  The only differe
2d940 6e 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a  nce between the.
2d950 2a 2a 20 74 77 6f 20 69 73 20 74 68 61 74 20 74  ** two is that t
2d960 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2d970 74 65 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66  ter, the name of
2d980 20 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 75   the (scalar) fu
2d990 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
2d9a0 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64  regate, is encod
2d9b0 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 20  ed in UTF-8 for 
2d9c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2d9d0 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54  unction() and UT
2d9e0 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  F-16.** for sqli
2d9f0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2da00 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  ion16()..**.** T
2da10 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2da20 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
2da30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2da40 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
2da50 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
2da60 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 49 66  to be added.  If
2da70 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 61   a single progra
2da80 6d 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  m uses more than
2da90 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
2daa0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65   connection inte
2dab0 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c  rnally, then SQL
2dac0 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
2dad0 62 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 64  be added individ
2dae0 75 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68  ually to.** each
2daf0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2db00 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
2db10 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2db20 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
2db30 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2db40 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f   to be created o
2db50 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20  r.** redefined. 
2db60 20 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   The length of t
2db70 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
2db80 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c  ed to 255 bytes,
2db90 20 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a   exclusive of.**
2dba0 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
2dbb0 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74  ator.  Note that
2dbc0 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68   the name length
2dbd0 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74   limit is in byt
2dbe0 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61  es, not.** chara
2dbf0 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65  cters.  Any atte
2dc00 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
2dc10 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
2dc20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
2dc30 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53  ill result in [S
2dc40 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69  QLITE_ERROR] bei
2dc50 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
2dc60 2a 2a 20 54 68 65 20 74 68 69 72 64 20 70 61 72  ** The third par
2dc70 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
2dc80 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
2dc90 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
2dca0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2dcb0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2dcc0 65 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73  e takes. If this
2dcd0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65   parameter is ne
2dce0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
2dcf0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2dd00 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
2dd10 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
2dd20 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a  r of arguments..
2dd30 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68  **.** The fourth
2dd40 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
2dd50 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
2dd60 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
2dd70 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
2dd80 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
2dd90 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
2dda0 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
2ddb0 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20  eters.  Any SQL 
2ddc0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2ddd0 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  ntation should b
2dde0 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a  e able to work.*
2ddf0 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d  * work with UTF-
2de00 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20  8, UTF-16le, or 
2de10 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73  UTF-16be.  But s
2de20 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ome implementati
2de30 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f  ons may be.** mo
2de40 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74  re efficient wit
2de50 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74  h one encoding t
2de60 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74  han another.  It
2de70 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a   is allowed to.*
2de80 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
2de90 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2dea0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
2deb0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2dec0 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  ) multiple.** ti
2ded0 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
2dee0 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77  e function but w
2def0 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61  ith different va
2df00 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70  lues of eTextRep
2df10 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70  ..** When multip
2df20 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2df30 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
2df40 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69  unction are avai
2df50 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a  lable, SQLite.**
2df60 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f   will pick the o
2df70 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73  ne that involves
2df80 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
2df90 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72  t of data conver
2dfa0 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72  sion..** If ther
2dfb0 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67  e is only a sing
2dfc0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2dfd0 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74  n which does not
2dfe0 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a   care what text.
2dff0 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  ** encoding is u
2e000 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  sed, then the fo
2e010 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68  urth argument sh
2e020 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f  ould be [SQLITE_
2e030 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ANY]..**.** The 
2e040 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
2e050 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
2e060 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
2e070 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2e080 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
2e090 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
2e0a0 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
2e0b0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
2e0c0 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a  ser_data()]..**.
2e0d0 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20  ** The seventh, 
2e0e0 65 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68  eighth and ninth
2e0f0 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75   parameters, xFu
2e100 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46  nc, xStep and xF
2e110 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69  inal, are.** poi
2e120 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75  nters to C-langu
2e130 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  age functions th
2e140 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
2e150 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2e160 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 41  .** aggregate. A
2e170 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
2e180 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
2e190 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2e1a0 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20  of the xFunc.** 
2e1b0 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e  callback only, N
2e1c0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f  ULL pointers sho
2e1d0 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 61 73  uld be passed as
2e1e0 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
2e1f0 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
2e200 65 72 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74  ers. An aggregat
2e210 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
2e220 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
2e230 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74  mentation of xSt
2e240 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c  ep.** and xFinal
2e250 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64   and NULL should
2e260 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78   be passed for x
2e270 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20  Func. To delete 
2e280 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53  an existing.** S
2e290 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
2e2a0 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e  ggregate, pass N
2e2b0 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ULL for all thre
2e2c0 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  e function callb
2e2d0 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69  acks..**.** It i
2e2e0 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72  s permitted to r
2e2f0 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65  egister multiple
2e300 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2e310 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
2e320 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74  functions with t
2e330 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
2e340 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66   with either dif
2e350 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f  fering numbers o
2e360 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f  f.** arguments o
2e370 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66  r differing pref
2e380 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
2e390 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77 69  ings.  SQLite wi
2e3a0 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
2e3b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73  plementation mos
2e3c0 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65  t closely matche
2e3d0 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69  s the way in whi
2e3e0 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75  ch the.** SQL fu
2e3f0 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20  nction is used. 
2e400 20 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   A function impl
2e410 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
2e420 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a  a non-negative.*
2e430 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72  * nArg parameter
2e440 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74   is a better mat
2e450 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
2e460 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2e470 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61  n with.** a nega
2e480 74 69 76 65 20 6e 41 72 67 2e 20 20 41 20 66 75  tive nArg.  A fu
2e490 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
2e4a0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
2e4b0 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
2e4c0 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
2e4d0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
2e4e0 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
2e4f0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
2e500 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
2e510 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
2e520 20 0a 2a 2a 20 41 20 66 75 6e 63 74 69 6f 6e 20   .** A function 
2e530 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
2e540 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
2e550 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
2e560 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
2e570 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
2e580 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
2e590 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
2e5a0 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
2e5b0 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
2e5c0 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
2e5d0 0a 2a 2a 20 42 75 69 6c 74 2d 69 6e 20 66 75 6e  .** Built-in fun
2e5e0 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76  ctions may be ov
2e5f0 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20  erloaded by new 
2e600 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2e610 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ned functions..*
2e620 2a 20 54 68 65 20 66 69 72 73 74 20 61 70 70 6c  * The first appl
2e630 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2e640 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
2e650 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76 65 72 72  given name overr
2e660 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c  ides all.** buil
2e670 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 69  t-in functions i
2e680 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
2e690 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2e6a0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
2e6b0 61 6d 65 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  ame..** Subseque
2e6c0 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  nt application-d
2e6d0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
2e6e0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 6e 61 6d   of the same nam
2e6f0 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69 64 65 20  e only override 
2e700 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70 6c 69 63  .** prior applic
2e710 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2e720 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  nctions that are
2e730 20 61 6e 20 65 78 61 63 74 20 6d 61 74 63 68 20   an exact match 
2e740 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  for the.** numbe
2e750 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20  r of parameters 
2e760 61 6e 64 20 70 72 65 66 65 72 72 65 64 20 65 6e  and preferred en
2e770 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e  coding..**.** An
2e780 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2e790 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
2e7a0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
2e7b0 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
2e7c0 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
2e7d0 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
2e7e0 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
2e7f0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
2e800 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
2e810 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
2e820 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
2e830 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
2e840 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
2e850 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2e860 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2e870 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 33 7d  :.**.** {H16103}
2e880 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   The [sqlite3_cr
2e890 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2e8a0 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  D,X,...)] interf
2e8b0 61 63 65 20 73 68 61 6c 6c 20 62 65 68 61 76 65  ace shall behave
2e8c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20  .**          as 
2e8d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2e8e0 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e  function(D,X,...
2e8f0 29 5d 20 69 6e 20 65 76 65 72 79 20 77 61 79 20  )] in every way 
2e900 65 78 63 65 70 74 20 74 68 61 74 20 69 74 0a 2a  except that it.*
2e910 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
2e920 70 72 65 74 73 20 74 68 65 20 58 20 61 72 67 75  prets the X argu
2e930 6d 65 6e 74 20 61 73 20 7a 65 72 6f 2d 74 65 72  ment as zero-ter
2e940 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 0a 2a  minated UTF-16.*
2e950 2a 20 20 20 20 20 20 20 20 20 20 6e 61 74 69 76  *          nativ
2e960 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73  e byte order ins
2e970 74 65 61 64 20 6f 66 20 61 73 20 7a 65 72 6f 2d  tead of as zero-
2e980 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
2e990 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 36 7d  ..**.** {H16106}
2e9a0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
2e9b0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  vocation of the.
2e9c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2e9d0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2e9e0 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e  tion(D,X,N,E,...
2e9f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  )] interface sha
2ea00 6c 6c 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 20  ll register.**  
2ea10 20 20 20 20 20 20 20 20 6f 72 20 72 65 70 6c 61          or repla
2ea20 63 65 73 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ces callback fun
2ea30 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 5b 64  ctions in the [d
2ea40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ea50 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20  on] D.**        
2ea60 20 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d    used to implem
2ea70 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
2ea80 74 69 6f 6e 20 6e 61 6d 65 64 20 58 20 77 69 74  tion named X wit
2ea90 68 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  h N parameters.*
2eaa0 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 68  *          and h
2eab0 61 76 69 6e 67 20 61 20 70 72 65 66 65 72 72 65  aving a preferre
2eac0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  d text encoding 
2ead0 6f 66 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  of E..**.** {H16
2eae0 31 30 39 7d 20 41 20 73 75 63 63 65 73 73 66 75  109} A successfu
2eaf0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
2eb00 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2eb10 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53  on(D,X,N,E,P,F,S
2eb20 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,L)].**         
2eb30 20 73 68 61 6c 6c 20 72 65 70 6c 61 63 65 20 74   shall replace t
2eb40 68 65 20 50 2c 20 46 2c 20 53 2c 20 61 6e 64 20  he P, F, S, and 
2eb50 4c 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 61 6e  L values from an
2eb60 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 77 69  y prior calls wi
2eb70 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  th.**          t
2eb80 68 65 20 73 61 6d 65 20 44 2c 20 58 2c 20 4e 2c  he same D, X, N,
2eb90 20 61 6e 64 20 45 20 76 61 6c 75 65 73 2e 0a 2a   and E values..*
2eba0 2a 0a 2a 2a 20 7b 48 31 36 31 31 32 7d 20 54 68  *.** {H16112} Th
2ebb0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2ebc0 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e  e_function(D,X,.
2ebd0 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73  ..)] interface s
2ebe0 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20  hall fail.**    
2ebf0 20 20 20 20 20 20 69 66 20 74 68 65 20 53 51 4c        if the SQL
2ec00 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 20 58   function name X
2ec10 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
2ec20 6c 6f 6e 67 65 72 20 74 68 61 6e 20 32 35 35 20  longer than 255 
2ec30 62 79 74 65 73 20 65 78 63 6c 75 73 69 76 65 20  bytes exclusive 
2ec40 6f 66 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  of the zero term
2ec50 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  inator..**.** {H
2ec60 31 36 31 31 38 7d 20 54 68 65 20 5b 73 71 6c 69  16118} The [sqli
2ec70 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ec80 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  ion(D,X,N,E,P,F,
2ec90 53 2c 4c 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  S,L)] interface.
2eca0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c  **          shal
2ecb0 6c 20 66 61 69 6c 20 75 6e 6c 65 73 73 20 65 69  l fail unless ei
2ecc0 74 68 65 72 20 46 20 69 73 20 4e 55 4c 4c 20 61  ther F is NULL a
2ecd0 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65 20 6e  nd S and L are n
2ece0 6f 6e 2d 4e 55 4c 4c 20 6f 72 0a 2a 2a 2a 20 20  on-NULL or.***  
2ecf0 20 20 20 20 20 20 20 46 20 69 73 20 6e 6f 6e 2d         F is non-
2ed00 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c  NULL and S and L
2ed10 20 61 72 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a   are NULL..**.**
2ed20 20 7b 48 31 36 31 32 31 7d 20 54 68 65 20 5b 73   {H16121} The [s
2ed30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2ed40 6e 63 74 69 6f 6e 28 44 2c 2e 2e 2e 29 5d 20 69  nction(D,...)] i
2ed50 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 66  nterface shall f
2ed60 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20  ails with an.** 
2ed70 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 63           error c
2ed80 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42  ode of [SQLITE_B
2ed90 55 53 59 5d 20 69 66 20 74 68 65 72 65 20 65 78  USY] if there ex
2eda0 69 73 74 20 5b 70 72 65 70 61 72 65 64 20 73 74  ist [prepared st
2edb0 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20 20 20  atements].**    
2edc0 20 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 64        associated
2edd0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
2ede0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2edf0 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 34  D..**.** {H16124
2ee00 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2ee10 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2ee20 2c 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  ,X,N,...)] inter
2ee30 66 61 63 65 20 73 68 61 6c 6c 20 66 61 69 6c 20  face shall fail 
2ee40 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  with.**         
2ee50 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 6f   an error code o
2ee60 66 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  f [SQLITE_ERROR]
2ee70 20 69 66 20 70 61 72 61 6d 65 74 65 72 20 4e 20   if parameter N 
2ee80 69 73 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20  is less.**      
2ee90 20 20 20 20 74 68 61 6e 20 2d 31 20 6f 72 20 67      than -1 or g
2eea0 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 2e  reater than 127.
2eeb0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 37 7d 20  .**.** {H16127} 
2eec0 57 68 65 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65  When N is non-ne
2eed0 67 61 74 69 76 65 2c 20 74 68 65 20 5b 73 71 6c  gative, the [sql
2eee0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2eef0 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d  tion(D,X,N,...)]
2ef00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
2ef10 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 67  erface shall reg
2ef20 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 73 20  ister callbacks 
2ef30 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f  to be invoked fo
2ef40 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
2ef50 20 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a    SQL function.*
2ef60 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 64  *          named
2ef70 20 58 20 77 68 65 6e 20 74 68 65 20 6e 75 6d 62   X when the numb
2ef80 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2ef90 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
2efa0 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ion is.**       
2efb0 20 20 20 65 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a     exactly N..**
2efc0 0a 2a 2a 20 7b 48 31 36 31 33 30 7d 20 57 68 65  .** {H16130} Whe
2efd0 6e 20 4e 20 69 73 20 2d 31 2c 20 74 68 65 20 5b  n N is -1, the [
2efe0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2eff0 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e  unction(D,X,N,..
2f000 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
2f010 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
2f020 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
2f030 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ks to be invoked
2f040 20 66 6f 72 20 74 68 65 20 53 51 4c 0a 2a 2a 20   for the SQL.** 
2f050 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f           functio
2f060 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20 61  n named X with a
2f070 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
2f080 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  uments..**.** {H
2f090 31 36 31 33 33 7d 20 57 68 65 6e 20 63 61 6c 6c  16133} When call
2f0a0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  s to [sqlite3_cr
2f0b0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2f0c0 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  X,N,...)].**    
2f0d0 20 20 20 20 20 20 73 70 65 63 69 66 79 20 6d 75        specify mu
2f0e0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
2f0f0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2f100 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a  me function X.**
2f110 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 77 68            and wh
2f120 65 6e 20 6f 6e 65 20 69 6d 70 6c 65 6d 65 6e 74  en one implement
2f130 61 74 69 6f 6e 20 68 61 73 20 4e 3e 3d 30 20 61  ation has N>=0 a
2f140 6e 64 20 74 68 65 20 6f 74 68 65 72 20 68 61 73  nd the other has
2f150 20 4e 3d 28 2d 31 29 0a 2a 2a 20 20 20 20 20 20   N=(-1).**      
2f160 20 20 20 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e      the implemen
2f170 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
2f180 6e 2d 7a 65 72 6f 20 4e 20 73 68 61 6c 6c 20 62  n-zero N shall b
2f190 65 20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a  e preferred..**.
2f1a0 2a 2a 20 7b 48 31 36 31 33 36 7d 20 57 68 65 6e  ** {H16136} When
2f1b0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
2f1c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2f1d0 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d  on(D,X,N,E,...)]
2f1e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70 65  .**          spe
2f1f0 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d  cify multiple im
2f200 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2f210 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2f220 6f 6e 20 58 20 77 69 74 68 0a 2a 2a 20 20 20 20  on X with.**    
2f230 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 6e        the same n
2f240 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2f250 74 73 20 4e 20 62 75 74 20 77 69 74 68 20 64 69  ts N but with di
2f260 66 66 65 72 65 6e 74 0a 2a 2a 20 20 20 20 20 20  fferent.**      
2f270 20 20 20 20 65 6e 63 6f 64 69 6e 67 73 20 45 2c      encodings E,
2f280 20 74 68 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d   then the implem
2f290 65 6e 74 61 74 69 6f 6e 20 77 68 65 72 65 20 45  entation where E
2f2a0 20 6d 61 74 63 68 65 73 20 74 68 65 0a 2a 2a 20   matches the.** 
2f2b0 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73           databas
2f2c0 65 20 65 6e 63 6f 64 69 6e 67 20 73 68 61 6c 6c  e encoding shall
2f2d0 20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a   preferred..**.*
2f2e0 2a 20 7b 48 31 36 31 33 39 7d 20 46 6f 72 20 61  * {H16139} For a
2f2f0 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
2f300 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 65 64  function created
2f310 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
2f320 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61     [sqlite3_crea
2f330 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2f340 4e 2c 45 2c 50 2c 30 2c 53 2c 4c 29 5d 20 74 68  N,E,P,0,S,L)] th
2f350 65 20 66 69 6e 61 6c 69 7a 65 72 0a 2a 2a 20 20  e finalizer.**  
2f360 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e          function
2f370 20 4c 20 73 68 61 6c 6c 20 61 6c 77 61 79 73 20   L shall always 
2f380 62 65 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74  be invoked exact
2f390 6c 79 20 6f 6e 63 65 20 69 66 20 74 68 65 0a 2a  ly once if the.*
2f3a0 2a 20 20 20 20 20 20 20 20 20 20 73 74 65 70 20  *          step 
2f3b0 66 75 6e 63 74 69 6f 6e 20 53 20 69 73 20 63 61  function S is ca
2f3c0 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
2f3d0 20 74 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48   times..**.** {H
2f3e0 31 36 31 34 32 7d 20 57 68 65 6e 20 53 51 4c 69  16142} When SQLi
2f3f0 74 65 20 69 6e 76 6f 6b 65 73 20 65 69 74 68 65  te invokes eithe
2f400 72 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78  r the xFunc or x
2f410 53 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 6f 66  Step function of
2f420 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20  .**          an 
2f430 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2f440 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2f450 20 6f 72 20 61 67 67 72 65 67 61 74 65 20 63 72   or aggregate cr
2f460 65 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  eated.**        
2f470 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 72    by [sqlite3_cr
2f480 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2f490 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   or [sqlite3_cre
2f4a0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2f4b0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ],.**          t
2f4c0 68 65 6e 20 74 68 65 20 61 72 72 61 79 20 6f 66  hen the array of
2f4d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2f4e0 20 6f 62 6a 65 63 74 73 20 70 61 73 73 65 64 20   objects passed 
2f4f0 61 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  as the.**       
2f500 20 20 20 74 68 69 72 64 20 70 61 72 61 6d 65 74     third paramet
2f510 65 72 20 73 68 61 6c 6c 20 62 65 20 5b 70 72 6f  er shall be [pro
2f520 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2f530 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
2f540 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
2f550 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
2f560 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
2f570 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
2f580 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
2f590 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
2f5a0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
2f5b0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
2f5c0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
2f5d0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2f5e0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2f5f0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
2f600 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2f610 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2f620 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
2f630 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
2f640 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
2f650 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2f660 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
2f670 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
2f680 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
2f690 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2f6a0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2f6b0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2f6c0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2f6d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2f6e0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2f6f0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2f700 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2f710 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2f720 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2f730 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2f740 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
2f750 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f760 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
2f770 73 20 7b 48 31 30 32 36 37 7d 20 3c 53 35 30 32  s {H10267} <S502
2f780 30 30 3e 20 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a  00> <H16100>.**.
2f790 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2f7a0 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
2f7b0 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
2f7c0 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
2f7d0 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
2f7e0 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
2f7f0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
2f800 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
2f810 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
2f820 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2f830 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  LE        2.#def
2f840 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2f850 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66  BE        3.#def
2f860 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2f870 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
2f880 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
2f890 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
2f8a0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
2f8b0 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
2f8c0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2f8d0 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  function only */
2f8e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2f8f0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
2f900 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
2f910 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
2f920 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
2f930 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
2f940 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ted Functions.**
2f950 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
2f960 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
2f970 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65  s are [deprecate
2f980 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  d].  In order to
2f990 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
2f9a0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
2f9b0 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
2f9c0 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63  code, these func
2f9d0 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a  tions continue .
2f9e0 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ** to be support
2f9f0 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ed.  However, ne
2fa00 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
2fa10 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
2fa20 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
2fa30 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68  functions.  To h
2fa40 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65  elp encourage pe
2fa50 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  ople to avoid.**
2fa60 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e   using these fun
2fa70 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e  ctions, we are n
2fa80 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c  ot going to tell
2fa90 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64   you what they d
2faa0 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  o..*/.#ifndef SQ
2fab0 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43  LITE_OMIT_DEPREC
2fac0 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52  ATED.SQLITE_DEPR
2fad0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2fae0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
2faf0 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
2fb00 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  xt*);.SQLITE_DEP
2fb10 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2fb20 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
2fb30 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
2fb40 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
2fb50 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
2fb60 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
2fb70 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
2fb80 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
2fb90 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2fba0 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
2fbb0 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
2fbc0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2fbd0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
2fbe0 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
2fbf0 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
2fc00 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2fc10 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
2fc20 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
2fc30 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
2fc40 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
2fc50 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  t64);.#endif../*
2fc60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
2fc70 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63  taining SQL Func
2fc80 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56  tion Parameter V
2fc90 61 6c 75 65 73 20 7b 48 31 35 31 30 30 7d 20 3c  alues {H15100} <
2fca0 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
2fcb0 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
2fcc0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
2fcd0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
2fce0 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
2fcf0 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
2fd00 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
2fd10 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
2fd20 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
2fd30 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
2fd40 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
2fd50 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75  e..**.** The xFu
2fd60 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
2fd70 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
2fd80 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
2fd90 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
2fda0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
2fdb0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2fdc0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
2fdd0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2fde0 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
2fdf0 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
2fe00 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
2fe10 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
2fe20 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34  egates..** The 4
2fe30 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2fe40 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
2fe50 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
2fe60 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
2fe70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2fe80 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
2fe90 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
2fea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2feb0 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
2fec0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
2fed0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
2fee0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
2fef0 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
2ff00 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
2ff10 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
2ff20 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
2ff30 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2ff40 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
2ff50 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
2ff60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2ff70 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
2ff80 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
2ff90 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
2ffa0 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
2ffb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
2ffc0 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
2ffd0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
2ffe0 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  havior..**.** Th
2fff0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
30000 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
30010 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
30020 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
30030 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
30040 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f  t that  these ro
30050 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
30060 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
30070 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
30080 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
30090 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
300a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
300b0 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
300c0 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
300d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
300e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
300f0 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
30100 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36  xtracts a UTF-16
30110 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68   string.** in th
30120 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72  e native byte-or
30130 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
30140 6d 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a  machine.  The.**
30150 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
30160 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
30170 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
30180 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
30190 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
301a0 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62  -16 strings as b
301b0 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69  ig-endian and li
301c0 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70  ttle-endian resp
301d0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
301e0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
301f0 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29  e_numeric_type()
30200 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
30210 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20  pts to apply.** 
30220 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79  numeric affinity
30230 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20   to the value.  
30240 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
30250 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a  an attempt is.**
30260 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74   made to convert
30270 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e   the value to an
30280 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61   integer or floa
30290 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a  ting point.  If.
302a0 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72  ** such a conver
302b0 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65  sion is possible
302c0 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
302d0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e   information (in
302e0 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c   other.** words,
302f0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73   if the value is
30300 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c   a string that l
30310 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62  ooks like a numb
30320 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  er).** then the 
30330 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65  conversion is pe
30340 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77  rformed.  Otherw
30350 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
30360 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65  n occurs..** The
30370 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
30380 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
30390 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
303a0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
303b0 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
303c0 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
303d0 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
303e0 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65  t the pointer re
303f0 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
30400 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
30410 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
30420 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
30430 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  r.** [sqlite3_va
30440 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61  lue_text16()] ca
30450 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  n be invalidated
30460 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74   by a subsequent
30470 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
30480 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
30490 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
304a0 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20  lue_bytes16()], 
304b0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
304c0 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
304d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
304e0 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  t16()]..**.** Th
304f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
30500 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
30510 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
30520 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
30530 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
30540 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74  plied the [sqlit
30550 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d  e3_value*] param
30560 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  eters..**.** INV
30570 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
30580 48 31 35 31 30 33 7d 20 54 68 65 20 5b 73 71 6c  H15103} The [sql
30590 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
305a0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
305b0 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
305c0 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
305d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
305e0 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
305f0 20 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e 0a 2a   BLOB and then.*
30600 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
30610 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
30620 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61  the converted va
30630 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31  lue..**.** {H151
30640 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  06} The [sqlite3
30650 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 56 29 5d  _value_bytes(V)]
30660 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
30670 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
30680 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74     number of byt
30690 65 73 20 69 6e 20 74 68 65 20 42 4c 4f 42 20 6f  es in the BLOB o
306a0 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73  r string (exclus
306b0 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ive of the.**   
306c0 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d         zero term
306d0 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74  inator on the st
306e0 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72  ring) that was r
306f0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
30700 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20  *          most 
30710 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
30720 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
30730 6f 62 28 56 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  ob(V)] or.**    
30740 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76        [sqlite3_v
30750 61 6c 75 65 5f 74 65 78 74 28 56 29 5d 2e 0a 2a  alue_text(V)]..*
30760 2a 0a 2a 2a 20 7b 48 31 35 31 30 39 7d 20 54 68  *.** {H15109} Th
30770 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
30780 5f 62 79 74 65 73 31 36 28 56 29 5d 20 69 6e 74  _bytes16(V)] int
30790 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
307a0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
307b0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
307c0 6e 20 74 68 65 20 73 74 72 69 6e 67 20 28 65 78  n the string (ex
307d0 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a  clusive of the.*
307e0 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20  *          zero 
307f0 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68  terminator on th
30800 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77  e string) that w
30810 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  as returned by t
30820 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  he.**          m
30830 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
30840 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  to [sqlite3_valu
30850 65 5f 74 65 78 74 31 36 28 56 29 5d 2c 0a 2a 2a  e_text16(V)],.**
30860 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
30870 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
30880 65 28 56 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  e(V)], or [sqlit
30890 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
308a0 65 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  e(V)]..**.** {H1
308b0 35 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  5112} The [sqlit
308c0 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
308d0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
308e0 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
308f0 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
30900 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
30910 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
30920 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
30930 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20  value and.**    
30940 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
30950 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c  copy of that val
30960 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31  ue..**.** {H1511
30970 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
30980 76 61 6c 75 65 5f 69 6e 74 28 56 29 5d 20 69 6e  value_int(V)] in
30990 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
309a0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
309b0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
309c0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
309d0 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69  t V into a 64-bi
309e0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
309f0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
30a00 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77   returns the low
30a10 65 72 20 33 32 20 62 69 74 73 20 6f 66 20 74 68  er 32 bits of th
30a20 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  at integer..**.*
30a30 2a 20 7b 48 31 35 31 31 38 7d 20 54 68 65 20 5b  * {H15118} The [
30a40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
30a50 74 36 34 28 56 29 5d 20 69 6e 74 65 72 66 61 63  t64(V)] interfac
30a60 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
30a70 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
30a80 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
30a90 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
30aa0 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e  to a 64-bit sign
30ab0 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a  ed integer and.*
30ac0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
30ad0 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61  ns a copy of tha
30ae0 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
30af0 20 7b 48 31 35 31 32 31 7d 20 54 68 65 20 5b 73   {H15121} The [s
30b00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30b10 74 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(V)] interface 
30b20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
30b30 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
30b40 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
30b50 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
30b60 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
30b70 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20  ed UTF-8.**     
30b80 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20       string and 
30b90 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
30ba0 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67  r to that string
30bb0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 34 7d  ..**.** {H15124}
30bc0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
30bd0 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d 20 69  lue_text16(V)] i
30be0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
30bf0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
30c00 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
30c10 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30c20 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f  ct V into a zero
30c30 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79  -terminated 2-by
30c40 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  te.**          a
30c50 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61  ligned UTF-16 na
30c60 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a  tive byte order.
30c70 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
30c80 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
30c90 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
30ca0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
30cb0 48 31 35 31 32 37 7d 20 54 68 65 20 5b 73 71 6c  H15127} The [sql
30cc0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
30cd0 36 62 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  6be(V)] interfac
30ce0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
30cf0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
30d00 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
30d10 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
30d20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
30d30 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20  ated 2-byte.**  
30d40 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20          aligned 
30d50 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61  UTF-16 big-endia
30d60 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  n.**          st
30d70 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
30d80 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
30d90 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  at string..**.**
30da0 20 7b 48 31 35 31 33 30 7d 20 54 68 65 20 5b 73   {H15130} The [s
30db0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30dc0 74 31 36 6c 65 28 56 29 5d 20 69 6e 74 65 72 66  t16le(V)] interf
30dd0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
30de0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
30df0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30e00 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
30e10 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
30e20 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a  inated 2-byte.**
30e30 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65            aligne
30e40 64 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d  d UTF-16 little-
30e50 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20  endian.**       
30e60 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65     string and re
30e70 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
30e80 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
30e90 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 33 7d 20 54  **.** {H15133} T
30ea0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
30eb0 65 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72  e_type(V)] inter
30ec0 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
30ed0 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20           one of 
30ee0 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b  [SQLITE_NULL], [
30ef0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
30f00 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
30f10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
30f20 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b  LITE_TEXT], or [
30f30 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20  SQLITE_BLOB] as 
30f40 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a  appropriate for.
30f50 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
30f60 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
30f70 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20  object V..**.** 
30f80 7b 48 31 35 31 33 36 7d 20 54 68 65 20 5b 73 71  {H15136} The [sq
30f90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
30fa0 72 69 63 5f 74 79 70 65 28 56 29 5d 20 69 6e 74  ric_type(V)] int
30fb0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 0a  erface converts.
30fc0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
30fd0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
30fe0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
30ff0 20 56 20 69 6e 74 6f 20 65 69 74 68 65 72 20 61   V into either a
31000 6e 20 69 6e 74 65 67 65 72 20 6f 72 0a 2a 2a 20  n integer or.** 
31010 20 20 20 20 20 20 20 20 20 61 20 66 6c 6f 61 74           a float
31020 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
31030 69 66 20 69 74 20 63 61 6e 20 64 6f 20 73 6f 20  if it can do so 
31040 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 0a  without loss of.
31050 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 66 6f  **          info
31060 72 6d 61 74 69 6f 6e 2c 20 61 6e 64 20 72 65 74  rmation, and ret
31070 75 72 6e 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  urns one of [SQL
31080 49 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20  ITE_NULL],.**   
31090 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49         [SQLITE_I
310a0 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45  NTEGER], [SQLITE
310b0 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
310c0 5f 54 45 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20  _TEXT], or.**   
310d0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 42         [SQLITE_B
310e0 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69  LOB] as appropri
310f0 61 74 65 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  ate for the.**  
31100 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
31110 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
31120 5d 20 6f 62 6a 65 63 74 20 56 20 61 66 74 65 72  ] object V after
31130 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
31140 61 74 74 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73  attempt..*/.cons
31150 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
31160 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
31170 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
31180 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
31190 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
311a0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
311b0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
311c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
311d0 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
311e0 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
311f0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
31200 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
31210 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
31220 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  *);.sqlite3_int6
31230 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
31240 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
31250 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  lue*);.const uns
31260 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
31270 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
31280 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31290 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
312a0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
312b0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
312c0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
312d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
312e0 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
312f0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
31300 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
31310 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
31320 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
31330 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
31340 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
31350 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
31360 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
31370 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
31380 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31390 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
313a0 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
313b0 74 65 78 74 20 7b 48 31 36 32 31 30 7d 20 3c 53  text {H16210} <S
313c0 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20200>.**.** The
313d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
313e0 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
313f0 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
31400 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  his routine to a
31410 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72  llocate.** a str
31420 75 63 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69  ucture for stori
31430 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a  ng their state..
31440 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
31450 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
31460 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
31470 78 74 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  xt() routine is 
31480 63 61 6c 6c 65 64 20 66 6f 72 20 61 0a 2a 2a 20  called for a.** 
31490 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
314a0 67 61 74 65 2c 20 53 51 4c 69 74 65 20 61 6c 6c  gate, SQLite all
314b0 6f 63 61 74 65 73 20 6e 42 79 74 65 73 20 6f 66  ocates nBytes of
314c0 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
314d0 6f 75 74 20 74 68 61 74 0a 2a 2a 20 6d 65 6d 6f  out that.** memo
314e0 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
314f0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e  a pointer to it.
31500 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73   On second and s
31510 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
31520 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
31530 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
31540 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
31550 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
31560 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20 74 68 65 20  n index,.** the 
31570 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
31580 65 74 75 72 6e 65 64 2e 20 54 68 65 20 69 6d 70  eturned. The imp
31590 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
315a0 68 65 20 61 67 67 72 65 67 61 74 65 20 63 61 6e  he aggregate can
315b0 20 75 73 65 0a 2a 2a 20 74 68 65 20 72 65 74 75   use.** the retu
315c0 72 6e 65 64 20 62 75 66 66 65 72 20 74 6f 20 61  rned buffer to a
315d0 63 63 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a  ccumulate data..
315e0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 61 75 74  **.** SQLite aut
315f0 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
31600 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   the allocated b
31610 75 66 66 65 72 20 77 68 65 6e 20 74 68 65 20 61  uffer when the a
31620 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 75 65 72  ggregate.** quer
31630 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
31640 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
31650 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65  ameter should be
31660 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
31670 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
31680 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
31690 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
316a0 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
316b0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
316c0 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
316d0 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
316e0 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  s the aggregate 
316f0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
31700 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
31710 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
31720 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
31730 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
31740 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
31750 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
31760 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ng..**.** INVARI
31770 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ANTS:.**.** {H16
31780 32 31 31 7d 20 54 68 65 20 66 69 72 73 74 20 69  211} The first i
31790 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
317a0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
317b0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f  context(C,N)] fo
317c0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  r.**          a 
317d0 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61  particular insta
317e0 6e 63 65 20 6f 66 20 61 6e 20 61 67 67 72 65 67  nce of an aggreg
317f0 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 28 66 6f  ate function (fo
31800 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
31810 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65  *          conte
31820 78 74 20 43 29 20 63 61 75 73 65 73 20 53 51 4c  xt C) causes SQL
31830 69 74 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ite to allocate 
31840 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
31850 79 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  y,.**          z
31860 65 72 6f 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  ero that memory,
31870 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f   and return a po
31880 69 6e 74 65 72 20 74 6f 20 74 68 65 20 61 6c 6c  inter to the all
31890 6f 63 61 74 65 64 20 6d 65 6d 6f 72 79 2e 0a 2a  ocated memory..*
318a0 2a 0a 2a 2a 20 7b 48 31 36 32 31 33 7d 20 49 66  *.** {H16213} If
318b0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
318c0 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
318d0 73 20 64 75 72 69 6e 67 0a 2a 2a 20 20 20 20 20  s during.**     
318e0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67       [sqlite3_ag
318f0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
31900 43 2c 4e 29 5d 20 74 68 65 6e 20 74 68 65 20 66  C,N)] then the f
31910 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
31920 30 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 35  0..**.** {H16215
31930 7d 20 53 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  } Second and sub
31940 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
31950 6f 6e 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ons of.**       
31960 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72     [sqlite3_aggr
31970 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
31980 4e 29 5d 20 66 6f 72 20 74 68 65 20 73 61 6d 65  N)] for the same
31990 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72   context pointer
319a0 20 43 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69   C.**          i
319b0 67 6e 6f 72 65 20 74 68 65 20 4e 20 70 61 72 61  gnore the N para
319c0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
319d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
319e0 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
319f0 20 20 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f     block of memo
31a00 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ry returned by t
31a10 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74  he first invocat
31a20 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  ion..**.** {H162
31a30 31 37 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  17} The memory a
31a40 6c 6c 6f 63 61 74 65 64 20 62 79 20 5b 73 71 6c  llocated by [sql
31a50 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
31a60 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 69 73 0a  ontext(C,N)] is.
31a70 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f  **          auto
31a80 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20  matically freed 
31a90 6f 6e 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  on the next call
31aa0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
31ab0 65 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  et()].**        
31ac0 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69    or [sqlite3_fi
31ad0 6e 61 6c 69 7a 65 28 29 5d 20 66 6f 72 20 74 68  nalize()] for th
31ae0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
31af0 65 6d 65 6e 74 5d 20 63 6f 6e 74 61 69 6e 69 6e  ement] containin
31b00 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  g.**          th
31b10 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
31b20 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20  tion associated 
31b30 77 69 74 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a  with context C..
31b40 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
31b50 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
31b60 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
31b70 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29  xt*, int nBytes)
31b80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31b90 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72  F: User Data For
31ba0 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32   Functions {H162
31bb0 34 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a  40} <S20200>.**.
31bc0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
31bd0 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72  ser_data() inter
31be0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
31bf0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
31c00 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74  inter that was t
31c10 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72  he pUserData par
31c20 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20  ameter (the 5th 
31c30 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
31c40 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
31c50 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
31c60 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
31c70 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
31c80 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
31c90 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
31ca0 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
31cb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
31cc0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b  ined function. {
31cd0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  END}.**.** This 
31ce0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
31cf0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
31d00 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
31d10 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c  hich.** the appl
31d20 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
31d30 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
31d40 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ing..**.** INVAR
31d50 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
31d60 36 32 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  6243} The [sqlit
31d70 65 33 5f 75 73 65 72 5f 64 61 74 61 28 43 29 5d  e3_user_data(C)]
31d80 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
31d90 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
31da0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 50 20 70  .**          P p
31db0 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68 65 20  ointer from the 
31dc0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
31dd0 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
31de0 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20  ,P,F,S,L)].**   
31df0 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
31e00 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
31e10 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  on16(D,X,N,E,P,F
31e20 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74  ,S,L)] call that
31e30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
31e40 69 73 74 65 72 65 64 20 74 68 65 20 53 51 4c 20  istered the SQL 
31e50 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61  function associa
31e60 74 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  ted with [sqlite
31e70 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f  3_context] C..*/
31e80 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
31e90 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33  ser_data(sqlite3
31ea0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
31eb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
31ec0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
31ed0 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b   For Functions {
31ee0 48 31 36 32 35 30 7d 20 3c 53 36 30 36 30 30 3e  H16250} <S60600>
31ef0 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20200>.**.** T
31f00 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
31f10 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
31f20 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
31f30 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
31f40 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
31f50 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
31f60 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
31f70 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
31f80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
31f90 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
31fa0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
31fb0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
31fc0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
31fd0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
31fe0 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
31ff0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
32000 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
32010 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
32020 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 35 33 7d 20  .**.** {H16253} 
32030 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
32040 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 43  text_db_handle(C
32050 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
32060 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  urns a copy of t
32070 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 44  he.**          D
32080 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68   pointer from th
32090 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
320a0 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
320b0 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20  ,E,P,F,S,L)].** 
320c0 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
320d0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
320e0 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50  tion16(D,X,N,E,P
320f0 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68  ,F,S,L)] call th
32100 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  at.**          r
32110 65 67 69 73 74 65 72 65 64 20 74 68 65 20 53 51  egistered the SQ
32120 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63  L function assoc
32130 69 61 74 65 64 20 77 69 74 68 20 5b 73 71 6c 69  iated with [sqli
32140 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a  te3_context] C..
32150 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
32160 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
32170 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
32180 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
32190 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
321a0 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
321b0 61 20 7b 48 31 36 32 37 30 7d 20 3c 53 32 30 32  a {H16270} <S202
321c0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  00>.**.** The fo
321d0 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63  llowing two func
321e0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65  tions may be use
321f0 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20  d by scalar SQL 
32200 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20  functions to.** 
32210 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61  associate metada
32220 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
32230 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
32240 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
32250 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
32260 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
32270 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
32280 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
32290 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
322a0 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
322b0 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
322c0 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
322d0 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
322e0 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a  erved. This may.
322f0 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20  ** be used, for 
32300 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20  example, to add 
32310 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73  a regular-expres
32320 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63  sion matching sc
32330 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  alar.** function
32340 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
32350 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
32360 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
32370 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a   is stored as.**
32380 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
32390 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51  ated with the SQ
323a0 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  L value passed a
323b0 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  s the regular ex
323c0 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74  pression.** patt
323d0 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c  ern.  The compil
323e0 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  ed regular expre
323f0 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75  ssion can be reu
32400 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a  sed on multiple.
32410 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
32420 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
32430 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20  ion so that the 
32440 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e  original pattern
32450 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20   string.** does 
32460 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72  not need to be r
32470 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63  ecompiled on eac
32480 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a  h invocation..**
32490 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
324a0 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
324b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
324c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
324d0 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
324e0 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
324f0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
32500 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
32510 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
32520 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
32530 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
32540 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
32550 2e 20 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61  . If no metadata
32560 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a   has been ever.*
32570 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74  * been set for t
32580 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20  he Nth argument 
32590 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c  of the function,
325a0 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65   or if the corre
325b0 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63  sponding.** func
325c0 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68  tion parameter h
325d0 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65  as changed since
325e0 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77   the meta-data w
325f0 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20  as set,.** then 
32600 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
32610 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20  ata() returns a 
32620 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
32630 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
32640 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
32650 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68  terface saves th
32660 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f  e metadata.** po
32670 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20  inted to by its 
32680 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  3rd parameter as
32690 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f   the metadata fo
326a0 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72  r the N-th.** ar
326b0 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70  gument of the ap
326c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
326d0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62  d function.  Sub
326e0 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
326f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f   to sqlite3_get_
32700 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20  auxdata() might 
32710 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61  return this data
32720 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e  , if it has.** n
32730 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65  ot been destroye
32740 64 2e 0a 2a 2a 20 49 66 20 69 74 20 69 73 20 6e  d..** If it is n
32750 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20  ot NULL, SQLite 
32760 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
32770 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75  destructor.** fu
32780 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20  nction given by 
32790 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
327a0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  r to sqlite3_set
327b0 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a  _auxdata() on.**
327c0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68   the metadata wh
327d0 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
327e0 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ding function pa
327f0 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a  rameter changes.
32800 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53  ** or when the S
32810 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
32820 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65  pletes, whicheve
32830 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a  r comes first..*
32840 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66  *.** SQLite is f
32850 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20  ree to call the 
32860 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64  destructor and d
32870 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20  rop metadata on 
32880 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  any.** parameter
32890 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e   of any function
328a0 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 54   at any time.  T
328b0 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65  he only guarante
328c0 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  e is that.** the
328d0 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c   destructor will
328e0 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72   be called befor
328f0 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  e the metadata i
32900 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a  s dropped..**.**
32910 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65   In practice, me
32920 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
32930 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
32940 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
32950 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68  * expressions th
32960 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20  at are constant 
32970 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
32980 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c   This includes l
32990 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
329a0 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c   and SQL variabl
329b0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es..**.** These 
329c0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
329d0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
329e0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
329f0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
32a00 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
32a10 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ning..**.** INVA
32a20 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
32a30 31 36 32 37 32 7d 20 54 68 65 20 5b 73 71 6c 69  16272} The [sqli
32a40 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
32a50 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,N)] interface 
32a60 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
32a70 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  r.**          to
32a80 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
32a90 61 74 65 64 20 77 69 74 68 20 74 68 65 20 4e 74  ated with the Nt
32aa0 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  h parameter of t
32ab0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a  he SQL function.
32ac0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 6f 73  **          whos
32ad0 65 20 63 6f 6e 74 65 78 74 20 69 73 20 43 2c 20  e context is C, 
32ae0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65  or NULL if there
32af0 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 20   is no metadata 
32b00 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 20 20  associated.**   
32b10 20 20 20 20 20 20 20 77 69 74 68 20 74 68 61 74         with that
32b20 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
32b30 2a 20 7b 48 31 36 32 37 34 7d 20 54 68 65 20 5b  * {H16274} The [
32b40 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
32b50 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 6e  ata(C,N,P,D)] in
32b60 74 65 72 66 61 63 65 20 61 73 73 69 67 6e 73 20  terface assigns 
32b70 61 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20 20  a metadata.**   
32b80 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 50         pointer P
32b90 20 74 6f 20 74 68 65 20 4e 74 68 20 70 61 72 61   to the Nth para
32ba0 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c  meter of the SQL
32bb0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 63   function with c
32bc0 6f 6e 74 65 78 74 20 43 2e 0a 2a 2a 0a 2a 2a 20  ontext C..**.** 
32bd0 7b 48 31 36 32 37 36 7d 20 53 51 4c 69 74 65 20  {H16276} SQLite 
32be0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
32bf0 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69 74  destructor D wit
32c00 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  h a single argum
32c10 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ent.**          
32c20 77 68 69 63 68 20 69 73 20 74 68 65 20 6d 65 74  which is the met
32c30 61 64 61 74 61 20 70 6f 69 6e 74 65 72 20 50 20  adata pointer P 
32c40 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
32c50 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
32c60 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
32c70 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 77  data(C,N,P,D)] w
32c80 68 65 6e 20 53 51 4c 69 74 65 20 63 65 61 73 65  hen SQLite cease
32c90 73 20 74 6f 20 68 6f 6c 64 0a 2a 2a 20 20 20 20  s to hold.**    
32ca0 20 20 20 20 20 20 74 68 65 20 6d 65 74 61 64 61        the metada
32cb0 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37  ta..**.** {H1627
32cc0 37 7d 20 53 51 4c 69 74 65 20 63 65 61 73 65 73  7} SQLite ceases
32cd0 20 74 6f 20 68 6f 6c 64 20 6d 65 74 61 64 61 74   to hold metadat
32ce0 61 20 66 6f 72 20 61 6e 20 53 51 4c 20 66 75 6e  a for an SQL fun
32cf0 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a  ction parameter.
32d00 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e  **          when
32d10 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
32d20 61 74 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  at parameter cha
32d30 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  nges..**.** {H16
32d40 32 37 38 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74  278} When [sqlit
32d50 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
32d60 2c 4e 2c 50 2c 44 29 5d 20 69 73 20 69 6e 76 6f  ,N,P,D)] is invo
32d70 6b 65 64 2c 20 74 68 65 20 64 65 73 74 72 75 63  ked, the destruc
32d80 74 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tor.**          
32d90 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 6e  is called for an
32da0 79 20 70 72 69 6f 72 20 6d 65 74 61 64 61 74 61  y prior metadata
32db0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
32dc0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
32dd0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  on.**          c
32de0 6f 6e 74 65 78 74 20 43 20 61 6e 64 20 70 61 72  ontext C and par
32df0 61 6d 65 74 65 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20  ameter N..**.** 
32e00 7b 48 31 36 32 37 39 7d 20 53 51 4c 69 74 65 20  {H16279} SQLite 
32e10 77 69 6c 6c 20 63 61 6c 6c 20 64 65 73 74 72 75  will call destru
32e20 63 74 6f 72 73 20 66 6f 72 20 61 6e 79 20 6d 65  ctors for any me
32e30 74 61 64 61 74 61 20 69 74 20 69 73 20 68 6f 6c  tadata it is hol
32e40 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ding.**         
32e50 20 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72   in a particular
32e60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32e70 6d 65 6e 74 5d 20 53 20 77 68 65 6e 20 65 69 74  ment] S when eit
32e80 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
32e90 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
32ea0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
32eb0 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63  inalize(S)] is c
32ec0 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  alled..*/.void *
32ed0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
32ee0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
32ef0 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
32f00 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
32f10 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
32f20 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
32f30 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
32f40 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
32f50 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
32f60 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
32f70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
32f80 20 42 65 68 61 76 69 6f 72 20 7b 48 31 30 32 38   Behavior {H1028
32f90 30 7d 20 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a  0} <S30100>.**.*
32fa0 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
32fb0 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74  ial values for t
32fc0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
32fd0 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
32fe0 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
32ff0 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
33000 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
33010 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
33020 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73 74 72  ].  If the destr
33030 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  uctor.** argumen
33040 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54  t is SQLITE_STAT
33050 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  IC, it means tha
33060 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f  t the content po
33070 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e  inter is constan
33080 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65  t.** and will ne
33090 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20  ver change.  It 
330a0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
330b0 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20   be destroyed.  
330c0 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  The.** SQLITE_TR
330d0 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
330e0 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
330f0 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
33100 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
33110 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
33120 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
33130 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
33140 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
33150 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
33160 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
33170 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
33180 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
33190 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
331a0 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
331b0 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
331c0 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b  ilers.  See tick
331d0 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70  et #2191..*/.typ
331e0 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
331f0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
33200 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
33210 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
33220 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
33230 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
33240 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
33250 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
33260 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
33270 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
33280 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
33290 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
332a0 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
332b0 74 69 6f 6e 20 7b 48 31 36 34 30 30 7d 20 3c 53  tion {H16400} <S
332c0 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20200>.**.** The
332d0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
332e0 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
332f0 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
33300 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
33310 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
33320 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
33330 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
33340 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
33350 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
33360 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
33370 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
33380 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
33390 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
333a0 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
333b0 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
333c0 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65  like the [parame
333d0 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d  ter binding] fam
333e0 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69  ily of.** functi
333f0 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64  ons used to bind
33400 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
33410 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
33420 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33430 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
33440 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  he [SQL paramete
33450 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  r] documentation
33460 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
33470 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
33480 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
33490 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74  esult_blob() int
334a0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
334b0 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
334c0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
334d0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
334e0 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68  o be the BLOB wh
334f0 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70  ose content is p
33500 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20  ointed.** to by 
33510 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
33520 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69  eter and which i
33530 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77  s N bytes long w
33540 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
33550 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
33560 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
33570 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
33580 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73  lob() interfaces
33590 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20   set the result 
335a0 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
335b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
335c0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42  nction to be a B
335d0 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  LOB containing a
335e0 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73  ll zero.** bytes
335f0 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20   and N bytes in 
33600 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73  size, where N is
33610 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
33620 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
33630 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
33640 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
33650 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
33660 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
33670 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
33680 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
33690 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f  tion to be a flo
336a0 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
336b0 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
336c0 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  y its 2nd argume
336d0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  nt..**.** The sq
336e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
336f0 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
33700 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
33710 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63  ) functions.** c
33720 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ause the impleme
33730 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  nted SQL functio
33740 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  n to throw an ex
33750 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69  ception..** SQLi
33760 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69  te uses the stri
33770 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
33780 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61   the.** 2nd para
33790 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
337a0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
337b0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
337c0 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61  t_error16().** a
337d0 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e  s the text of an
337e0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
337f0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65   SQLite interpre
33800 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  ts the error.** 
33810 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66  message string f
33820 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
33830 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54  lt_error() as UT
33840 46 2d 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69  F-8. SQLite.** i
33850 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74  nterprets the st
33860 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
33870 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
33880 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  () as UTF-16 in 
33890 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f  native.** byte o
338a0 72 64 65 72 2e 20 20 49 66 20 74 68 65 20 74 68  rder.  If the th
338b0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
338c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
338d0 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
338e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
338f0 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69  or16() is negati
33900 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
33910 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f  akes as the erro
33920 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c  r.** message all
33930 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68   text up through
33940 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
33950 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66  character..** If
33960 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
33970 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
33980 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
33990 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
339a0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
339b0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68   non-negative th
339c0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
339d0 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74  that many.** byt
339e0 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
339f0 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  rs) from the 2nd
33a00 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
33a10 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
33a20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
33a30 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
33a40 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
33a50 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72  t_error16().** r
33a60 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70  outines make a p
33a70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
33a80 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
33a90 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20   text before.** 
33aa0 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65  they return.  He
33ab0 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  nce, the calling
33ac0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65   function can de
33ad0 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d  allocate or.** m
33ae0 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61  odify the text a
33af0 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e  fter they return
33b00 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
33b10 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
33b20 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
33b30 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67  ) function chang
33b40 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  es the error cod
33b50 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
33b60 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73   SQLite as a res
33b70 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ult of an error 
33b80 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20  in a function.  
33b90 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74  By default,.** t
33ba0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  he error code is
33bb0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
33bc0 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
33bd0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
33be0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
33bf0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
33c00 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
33c10 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
33c20 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
33c30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
33c40 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69  te3_result_toobi
33c50 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  g() interface ca
33c60 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
33c70 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a  hrow an error.**
33c80 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
33c90 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
33ca0 42 20 69 73 20 74 6f 20 6c 6f 6e 67 20 74 6f 20  B is to long to 
33cb0 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
33cc0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
33cd0 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ult_nomem() inte
33ce0 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
33cf0 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
33d00 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
33d10 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
33d20 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
33d30 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  led..**.** The s
33d40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
33d50 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  t() interface se
33d60 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
33d70 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
33d80 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33d90 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
33da0 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e   the 32-bit sign
33db0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
33dc0 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
33dd0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
33de0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
33df0 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
33e00 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
33e10 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
33e20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
33e30 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33e40 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
33e50 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
33e60 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
33e70 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
33e80 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
33e90 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33ea0 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  _null() interfac
33eb0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
33ec0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
33ed0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
33ee0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
33ef0 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  o be NULL..**.**
33f00 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
33f10 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  ult_text(), sqli
33f20 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
33f30 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  6(),.** sqlite3_
33f40 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
33f50 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
33f60 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29  esult_text16be()
33f70 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73   interfaces.** s
33f80 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  et the return va
33f90 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  lue of the appli
33fa0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
33fb0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  unction to be.**
33fc0 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77   a text string w
33fd0 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e  hich is represen
33fe0 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54  ted as UTF-8, UT
33ff0 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
34000 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31   order,.** UTF-1
34010 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c  6 little endian,
34020 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65   or UTF-16 big e
34030 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
34040 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74  ely..** SQLite t
34050 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65  akes the text re
34060 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70  sult from the ap
34070 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a  plication from.*
34080 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  * the 2nd parame
34090 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ter of the sqlit
340a0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
340b0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49  interfaces..** I
340c0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
340d0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
340e0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
340f0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
34100 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
34110 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73  SQLite takes res
34120 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68  ult text from th
34130 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  e 2nd parameter.
34140 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  ** through the f
34150 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
34160 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33  ter..** If the 3
34170 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
34180 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
34190 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
341a0 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65  ces.** is non-ne
341b0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20  gative, then as 
341c0 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20  many bytes (not 
341d0 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74  characters) of t
341e0 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74  he text.** point
341f0 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64  ed to by the 2nd
34200 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74   parameter are t
34210 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c  aken as the appl
34220 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a  ication-defined.
34230 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75  ** function resu
34240 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74  lt..** If the 4t
34250 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
34260 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34270 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
34280 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
34290 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
342a0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
342b0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
342c0 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
342d0 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
342e0 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
342f0 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
34300 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
34310 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
34320 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
34330 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72  * If the 4th par
34340 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
34350 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
34360 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72  t* interfaces or
34370 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
34380 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
34390 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
343a0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
343b0 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73  hen SQLite.** as
343c0 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
343d0 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
343e0 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e  lt is in constan
343f0 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  t space and does
34400 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65   not.** copy the
34410 20 69 74 20 6f 72 20 63 61 6c 6c 20 61 20 64 65   it or call a de
34420 73 74 72 75 63 74 6f 72 20 77 68 65 6e 20 69 74  structor when it
34430 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
34440 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
34450 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70  .** If the 4th p
34460 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
34470 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34480 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
34490 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
344a0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
344b0 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
344c0 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
344d0 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
344e0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
344f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
34500 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
34510 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
34520 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
34530 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
34540 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ns..**.** The sq
34550 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
34560 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ue() interface s
34570 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ets the result o
34580 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
34590 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
345a0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f  ction to be a co
345b0 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f  py the.** [unpro
345c0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
345d0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65  alue] object spe
345e0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e  cified by the 2n
345f0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
34600 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  e.** sqlite3_res
34610 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
34620 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
34630 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
34640 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20  e3_value].** so 
34650 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
34660 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
34670 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
34680 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
34690 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
346a0 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
346b0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
346c0 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
346d0 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f   harm..** A [pro
346e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
346f0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79  alue] object may
34700 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20   always be used 
34710 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70  where an.** [unp
34720 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
34730 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69  _value] object i
34740 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65  s required, so e
34750 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66  ither.** kind of
34760 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
34770 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75   object can be u
34780 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e  sed with this in
34790 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  terface..**.** I
347a0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
347b0 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
347c0 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66   within the diff
347d0 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20  erent thread.** 
347e0 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e  than the one con
347f0 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c  taining the appl
34800 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34810 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65  function that re
34820 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73  ceived.** the [s
34830 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
34840 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73  pointer, the res
34850 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
34860 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
34870 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ANTS:.**.** {H16
34880 34 30 33 7d 20 54 68 65 20 64 65 66 61 75 6c 74  403} The default
34890 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
348a0 6f 6d 20 61 6e 79 20 53 51 4c 20 66 75 6e 63 74  om any SQL funct
348b0 69 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ion is NULL..**.
348c0 2a 2a 20 7b 48 31 36 34 30 36 7d 20 54 68 65 20  ** {H16406} The 
348d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
348e0 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  blob(C,V,N,D)] i
348f0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
34900 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
34910 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
34920 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
34930 65 20 61 20 42 4c 4f 42 20 74 68 61 74 20 69 73  e a BLOB that is
34940 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20   N bytes.**     
34950 20 20 20 20 20 69 6e 20 6c 65 6e 67 74 68 20 61       in length a
34960 6e 64 20 77 69 74 68 20 63 6f 6e 74 65 6e 74 20  nd with content 
34970 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2e  pointed to by V.
34980 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 39 7d 20  .**.** {H16409} 
34990 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
349a0 75 6c 74 5f 64 6f 75 62 6c 65 28 43 2c 56 29 5d  ult_double(C,V)]
349b0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
349c0 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
349d0 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
349e0 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
349f0 20 62 65 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   be the floating
34a00 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 56 2e 0a   point value V..
34a10 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 32 7d 20 54  **.** {H16412} T
34a20 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
34a30 6c 74 5f 65 72 72 6f 72 28 43 2c 56 2c 4e 29 5d  lt_error(C,V,N)]
34a40 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
34a50 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a  es the return.**
34a60 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
34a70 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
34a80 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e   be an exception
34a90 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65   with error code
34aa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
34ab0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20  LITE_ERROR] and 
34ac0 61 20 55 54 46 2d 38 20 65 72 72 6f 72 20 6d 65  a UTF-8 error me
34ad0 73 73 61 67 65 20 63 6f 70 69 65 64 20 66 72 6f  ssage copied fro
34ae0 6d 20 56 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  m V up to the.**
34af0 20 20 20 20 20 20 20 20 20 20 66 69 72 73 74 20            first 
34b00 7a 65 72 6f 20 62 79 74 65 20 6f 72 20 75 6e 74  zero byte or unt
34b10 69 6c 20 4e 20 62 79 74 65 73 20 61 72 65 20 72  il N bytes are r
34b20 65 61 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69  ead if N is posi
34b30 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  tive..**.** {H16
34b40 34 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  415} The [sqlite
34b50 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
34b60 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61  (C,V,N)] interfa
34b70 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
34b80 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
34b90 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74    value of funct
34ba0 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65  ion C to be an e
34bb0 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72  xception with er
34bc0 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20  ror code.**     
34bd0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52       [SQLITE_ERR
34be0 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 2d 31 36  OR] and a UTF-16
34bf0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
34c00 65 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  er error message
34c10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 70  .**          cop
34c20 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f  ied from V up to
34c30 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
34c40 74 65 72 6d 69 6e 61 74 6f 72 20 6f 72 20 75 6e  terminator or un
34c50 74 69 6c 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20  til N bytes.**  
34c60 20 20 20 20 20 20 20 20 61 72 65 20 72 65 61 64          are read
34c70 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76   if N is positiv
34c80 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 38  e..**.** {H16418
34c90 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
34ca0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
34cb0 69 67 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  ig(C)] interface
34cc0 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
34cd0 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
34ce0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e  value of the fun
34cf0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
34d00 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
34d10 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20  error code.**   
34d20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54         [SQLITE_T
34d30 4f 4f 42 49 47 5d 20 61 6e 64 20 61 6e 20 61 70  OOBIG] and an ap
34d40 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20  propriate error 
34d50 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b  message..**.** {
34d60 48 31 36 34 32 31 7d 20 54 68 65 20 5b 73 71 6c  H16421} The [sql
34d70 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34d80 72 5f 6e 6f 6d 65 6d 28 43 29 5d 20 69 6e 74 65  r_nomem(C)] inte
34d90 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
34da0 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
34db0 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68       value of th
34dc0 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  e function C to 
34dd0 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
34de0 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a  with error code.
34df0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
34e00 49 54 45 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20 61  ITE_NOMEM] and a
34e10 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72  n appropriate er
34e20 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
34e30 2a 2a 20 7b 48 31 36 34 32 34 7d 20 54 68 65 20  ** {H16424} The 
34e40 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
34e50 65 72 72 6f 72 5f 63 6f 64 65 28 43 2c 45 29 5d  error_code(C,E)]
34e60 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
34e70 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a  es the return.**
34e80 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
34e90 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
34ea0 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70  C to be an excep
34eb0 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20  tion with error 
34ec0 63 6f 64 65 20 45 2e 0a 2a 2a 20 20 20 20 20 20  code E..**      
34ed0 20 20 20 20 54 68 65 20 65 72 72 6f 72 20 6d 65      The error me
34ee0 73 73 61 67 65 20 74 65 78 74 20 69 73 20 75 6e  ssage text is un
34ef0 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  changed..**.** {
34f00 48 31 36 34 32 37 7d 20 54 68 65 20 5b 73 71 6c  H16427} The [sql
34f10 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
34f20 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,V)] interface 
34f30 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
34f40 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
34f50 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
34f60 20 43 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d   C to be the 32-
34f70 62 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75  bit integer valu
34f80 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  e V..**.** {H164
34f90 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  30} The [sqlite3
34fa0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 43 2c  _result_int64(C,
34fb0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  V)] interface ch
34fc0 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
34fd0 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
34fe0 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
34ff0 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
35000 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20  t integer value 
35010 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 33  V..**.** {H16433
35020 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
35030 65 73 75 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20 69  esult_null(C)] i
35040 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
35050 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
35060 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
35070 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
35080 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48  e NULL..**.** {H
35090 31 36 34 33 36 7d 20 54 68 65 20 5b 73 71 6c 69  16436} The [sqli
350a0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
350b0 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
350c0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
350d0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
350e0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
350f0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
35100 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
35110 20 20 20 20 20 20 20 20 20 20 56 20 75 70 20 74            V up t
35120 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
35130 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76   if N is negativ
35140 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  e.**          or
35150 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74   the first N byt
35160 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20  es of V if N is 
35170 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a  non-negative..**
35180 0a 2a 2a 20 7b 48 31 36 34 33 39 7d 20 54 68 65  .** {H16439} The
35190 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
351a0 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29  _text16(C,V,N,D)
351b0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
351c0 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
351d0 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
351e0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
351f0 6f 20 62 65 20 74 68 65 20 55 54 46 2d 31 36 20  o be the UTF-16 
35200 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
35210 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  r.**          st
35220 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65  ring V up to the
35230 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e   first zero if N
35240 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20   is negative.** 
35250 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
35260 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66  first N bytes of
35270 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e   V if N is non-n
35280 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
35290 48 31 36 34 34 32 7d 20 54 68 65 20 5b 73 71 6c  H16442} The [sql
352a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
352b0 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  16be(C,V,N,D)] i
352c0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
352d0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
352e0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
352f0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
35300 65 20 74 68 65 20 55 54 46 2d 31 36 20 62 69 67  e the UTF-16 big
35310 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20  -endian.**      
35320 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20      string V up 
35330 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
35340 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69  o if N is negati
35350 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ve.**          o
35360 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79  r the first N by
35370 74 65 73 20 6f 72 20 56 20 69 66 20 4e 20 69 73  tes or V if N is
35380 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a   non-negative..*
35390 2a 0a 2a 2a 20 7b 48 31 36 34 34 35 7d 20 54 68  *.** {H16445} Th
353a0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
353b0 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e  t_text16le(C,V,N
353c0 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
353d0 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
353e0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
353f0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
35400 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d  C to be the UTF-
35410 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  16 little-endian
35420 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
35430 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65 20  ing V up to the 
35440 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20  first zero if N 
35450 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20  is negative.**  
35460 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66          or the f
35470 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20  irst N bytes of 
35480 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65  V if N is non-ne
35490 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  gative..**.** {H
354a0 31 36 34 34 38 7d 20 54 68 65 20 5b 73 71 6c 69  16448} The [sqli
354b0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
354c0 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,V)] interface
354d0 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
354e0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
354f0 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
35500 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 5b 75  n C to be the [u
35510 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
35520 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 20 20 20  e3_value].**    
35530 20 20 20 20 20 20 6f 62 6a 65 63 74 20 56 2e 0a        object V..
35540 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 31 7d 20 54  **.** {H16451} T
35550 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
35560 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29  lt_zeroblob(C,N)
35570 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
35580 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
35590 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
355a0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
355b0 6f 20 62 65 20 61 6e 20 4e 2d 62 79 74 65 20 42  o be an N-byte B
355c0 4c 4f 42 20 6f 66 20 61 6c 6c 20 7a 65 72 6f 73  LOB of all zeros
355d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 34 7d  ..**.** {H16454}
355e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
355f0 73 75 6c 74 5f 65 72 72 6f 72 28 29 5d 20 61 6e  sult_error()] an
35600 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
35610 74 5f 65 72 72 6f 72 31 36 28 29 5d 0a 2a 2a 20  t_error16()].** 
35620 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
35630 63 65 73 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  ces make a copy 
35640 6f 66 20 74 68 65 69 72 20 65 72 72 6f 72 20 6d  of their error m
35650 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 62  essage strings b
35660 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20  efore.**        
35670 20 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a    returning..**.
35680 2a 2a 20 7b 48 31 36 34 35 37 7d 20 49 66 20 74  ** {H16457} If t
35690 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20  he D destructor 
356a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
356b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
356c0 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  b(C,V,N,D)],.** 
356d0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
356e0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c  3_result_text(C,
356f0 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65  V,N,D)], [sqlite
35700 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
35710 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
35720 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
35730 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
35740 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  C,V,N,D)], or.**
35750 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
35760 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
35770 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20  le(C,V,N,D)] is 
35780 74 68 65 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51  the constant [SQ
35790 4c 49 54 45 5f 53 54 41 54 49 43 5d 0a 2a 2a 20  LITE_STATIC].** 
357a0 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 6e 6f           then no
357b0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 65   destructor is e
357c0 76 65 72 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68  ver called on th
357d0 65 20 70 6f 69 6e 74 65 72 20 56 20 61 6e 64 20  e pointer V and 
357e0 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20 20  SQLite.**       
357f0 20 20 20 61 73 73 75 6d 65 73 20 74 68 61 74 20     assumes that 
35800 56 20 69 73 20 69 6d 6d 75 74 61 62 6c 65 2e 0a  V is immutable..
35810 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36 30 7d 20 49  **.** {H16460} I
35820 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74  f the D destruct
35830 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  or parameter to 
35840 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
35850 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a  blob(C,V,N,D)],.
35860 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
35870 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35880 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c  (C,V,N,D)], [sql
35890 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
358a0 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  16(C,V,N,D)],.**
358b0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
358c0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
358d0 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72  be(C,V,N,D)], or
358e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
358f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35900 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20  t16le(C,V,N,D)] 
35910 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 0a  is the constant.
35920 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
35930 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74  ITE_TRANSIENT] t
35940 68 65 6e 20 74 68 65 20 69 6e 74 65 72 66 61 63  hen the interfac
35950 65 73 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  es makes a copy 
35960 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
35970 20 20 20 63 6f 6e 74 65 6e 74 20 6f 66 20 56 20     content of V 
35980 61 6e 64 20 72 65 74 61 69 6e 73 20 74 68 65 20  and retains the 
35990 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  copy..**.** {H16
359a0 34 36 33 7d 20 49 66 20 74 68 65 20 44 20 64 65  463} If the D de
359b0 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74  structor paramet
359c0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  er to [sqlite3_r
359d0 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
359e0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
359f0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
35a00 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d  t_text(C,V,N,D)]
35a10 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  , [sqlite3_resul
35a20 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
35a30 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
35a40 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
35a50 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
35a60 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
35a70 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
35a80 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c  lt_text16le(C,V,
35a90 4e 2c 44 29 5d 20 69 73 20 73 6f 6d 65 20 76 61  N,D)] is some va
35aa0 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a  lue other than.*
35ab0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63  *          the c
35ac0 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45  onstants [SQLITE
35ad0 5f 53 54 41 54 49 43 5d 20 61 6e 64 20 5b 53 51  _STATIC] and [SQ
35ae0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20  LITE_TRANSIENT] 
35af0 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
35b00 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
35b10 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
35b20 6f 72 20 44 20 77 69 74 68 20 56 20 61 73 20 69  or D with V as i
35b30 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  ts only argument
35b40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65  .**          whe
35b50 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  n it has finishe
35b60 64 20 77 69 74 68 20 74 68 65 20 56 20 76 61 6c  d with the V val
35b70 75 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ue..*/.void sqli
35b80 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
35b90 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35ba0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
35bb0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
35bc0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
35bd0 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
35be0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35bf0 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20  , double);.void 
35c00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35c10 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e  rror(sqlite3_con
35c20 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
35c30 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  r*, int);.void s
35c40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35c50 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ror16(sqlite3_co
35c60 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
35c70 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
35c80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35c90 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69  rror_toobig(sqli
35ca0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
35cb0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
35cc0 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73  lt_error_nomem(s
35cd0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
35ce0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
35cf0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
35d00 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35d10 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
35d20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
35d30 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35d40 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
35d50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
35d60 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
35d70 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  xt*, sqlite3_int
35d80 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  64);.void sqlite
35d90 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71  3_result_null(sq
35da0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
35db0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
35dc0 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65  sult_text(sqlite
35dd0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
35de0 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f  t char*, int, vo
35df0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
35e00 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
35e10 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  lt_text16(sqlite
35e20 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
35e30 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
35e40 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
35e50 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
35e60 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  lt_text16le(sqli
35e70 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
35e80 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
35e90 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
35ea0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35eb0 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c  ult_text16be(sql
35ec0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
35ed0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
35ee0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
35ef0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
35f00 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74  sult_value(sqlit
35f10 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
35f20 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f  ite3_value*);.vo
35f30 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
35f40 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  t_zeroblob(sqlit
35f50 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
35f60 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
35f70 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77  3REF: Define New
35f80 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65   Collating Seque
35f90 6e 63 65 73 20 7b 48 31 36 36 30 30 7d 20 3c 53  nces {H16600} <S
35fa0 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20300>.**.** The
35fb0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
35fc0 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77   used to add new
35fd0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
35fe0 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b  nces to the.** [
35ff0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36000 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61  ion] specified a
36010 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
36020 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
36030 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20  name of the new 
36040 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
36050 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20  ce is specified 
36060 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  as a UTF-8 strin
36070 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
36080 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
36090 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
360a0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
360b0 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
360c0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72  TF-16 string for
360d0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
360e0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49  collation16(). I
360f0 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74  n all cases.** t
36100 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65  he name is passe
36110 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
36120 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
36130 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  t..**.** The thi
36140 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20  rd argument may 
36150 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  be one of the co
36160 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f  nstants [SQLITE_
36170 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  UTF8],.** [SQLIT
36180 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53  E_UTF16LE] or [S
36190 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20  QLITE_UTF16BE], 
361a0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
361b0 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65  the user-supplie
361c0 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70  d.** routine exp
361d0 65 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 65  ects to be passe
361e0 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  d pointers to st
361f0 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73  rings encoded us
36200 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54  ing UTF-8,.** UT
36210 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69  F-16 little-endi
36220 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
36230 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g-endian, respec
36240 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74  tively. The.** t
36250 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69  hird argument mi
36260 67 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c  ght also be [SQL
36270 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
36280 44 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  D] to indicate t
36290 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69  hat.** the routi
362a0 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74  ne expects point
362b0 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f  ers to 16-bit wo
362c0 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e  rd aligned strin
362d0 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20  gs.** of UTF-16 
362e0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
362f0 74 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 20  te order of the 
36300 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a  host computer..*
36310 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  *.** A pointer t
36320 6f 20 74 68 65 20 75 73 65 72 20 73 75 70 70 6c  o the user suppl
36330 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  ied routine must
36340 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
36350 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d  e fifth.** argum
36360 65 6e 74 2e 20 20 49 66 20 69 74 20 69 73 20 4e  ent.  If it is N
36370 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65  ULL, this is the
36380 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e   same as deletin
36390 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a  g the collation.
363a0 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20  ** sequence (so 
363b0 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e  that SQLite cann
363c0 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f  ot call it anymo
363d0 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d  re)..** Each tim
363e0 65 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  e the applicatio
363f0 6e 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74  n supplied funct
36400 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ion is invoked, 
36410 69 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20  it is passed.** 
36420 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61 72  as its first par
36430 61 6d 65 74 65 72 20 61 20 63 6f 70 79 20 6f 66  ameter a copy of
36440 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65   the void* passe
36450 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
36460 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
36470 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36480 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  llation() or sql
36490 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
364a0 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a  ation16()..**.**
364b0 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61   The remaining a
364c0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
364d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70  application-supp
364e0 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65  lied routine are
364f0 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a   two strings,.**
36500 20 65 61 63 68 20 72 65 70 72 65 73 65 6e 74 65   each represente
36510 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c 20  d by a (length, 
36520 64 61 74 61 29 20 70 61 69 72 20 61 6e 64 20 65  data) pair and e
36530 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e  ncoded in the en
36540 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77  coding.** that w
36550 61 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65  as passed as the
36560 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
36570 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  when the collati
36580 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a  on sequence was.
36590 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20 7b  ** registered. {
365a0 45 4e 44 7d 20 20 54 68 65 20 61 70 70 6c 69 63  END}  The applic
365b0 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f  ation defined co
365c0 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20  llation routine 
365d0 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
365e0 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20   negative, zero 
365f0 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 20 74  or positive if t
36600 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20  he first string 
36610 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a  is less than,.**
36620 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72   equal to, or gr
36630 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73  eater than the s
36640 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e  econd string. i.
36650 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54  e. (STRING1 - ST
36660 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  RING2)..**.** Th
36670 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
36680 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
36690 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
366a0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
366b0 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  ion().** except 
366c0 74 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e  that it takes an
366d0 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20   extra argument 
366e0 77 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72  which is a destr
366f0 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65  uctor for.** the
36700 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65   collation.  The
36710 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
36720 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63  alled when the c
36730 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64  ollation is.** d
36740 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20  estroyed and is 
36750 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66  passed a copy of
36760 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
36770 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e  meter void* poin
36780 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ter.** of the sq
36790 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
367a0 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20  lation_v2()..** 
367b0 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64  Collations are d
367c0 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20 74 68  estroyed when th
367d0 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65  ey are overridde
367e0 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73  n by later calls
367f0 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61   to the.** colla
36800 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75  tion creation fu
36810 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20  nctions or when 
36820 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
36830 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f  nnection] is clo
36840 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  sed.** using [sq
36850 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
36860 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
36870 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 33 7d  :.**.** {H16603}
36880 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
36890 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  ll to the.**    
368a0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
368b0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
368c0 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
368d0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20   interface.**   
368e0 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 73         registers
368f0 20 66 75 6e 63 74 69 6f 6e 20 46 20 61 73 20 74   function F as t
36900 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75  he comparison fu
36910 6e 63 74 69 6f 6e 20 75 73 65 64 20 74 6f 0a 2a  nction used to.*
36920 2a 20 20 20 20 20 20 20 20 20 20 69 6d 70 6c 65  *          imple
36930 6d 65 6e 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 58  ment collation X
36940 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
36950 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20  e connection] B 
36960 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
36970 64 61 74 61 62 61 73 65 73 20 68 61 76 69 6e 67  databases having
36980 20 65 6e 63 6f 64 69 6e 67 20 45 2e 0a 2a 2a 0a   encoding E..**.
36990 2a 2a 20 7b 48 31 36 36 30 34 7d 20 53 51 4c 69  ** {H16604} SQLi
369a0 74 65 20 75 6e 64 65 72 73 74 61 6e 64 73 20 74  te understands t
369b0 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20 74  he X parameter t
369c0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
369d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
369e0 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
369f0 2c 50 2c 46 2c 44 29 5d 20 61 73 20 61 20 7a 65  ,P,F,D)] as a ze
36a00 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
36a10 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20            UTF-8 
36a20 73 74 72 69 6e 67 20 69 6e 20 77 68 69 63 68 20  string in which 
36a30 63 61 73 65 20 69 73 20 69 67 6e 6f 72 65 64 20  case is ignored 
36a40 66 6f 72 20 41 53 43 49 49 20 63 68 61 72 61 63  for ASCII charac
36a50 74 65 72 73 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ters and.**     
36a60 20 20 20 20 20 69 73 20 73 69 67 6e 69 66 69 63       is signific
36a70 61 6e 74 20 66 6f 72 20 6e 6f 6e 2d 41 53 43 49  ant for non-ASCI
36a80 49 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  I characters..**
36a90 0a 2a 2a 20 7b 48 31 36 36 30 36 7d 20 53 75 63  .** {H16606} Suc
36aa0 63 65 73 73 69 76 65 20 63 61 6c 6c 73 20 74 6f  cessive calls to
36ab0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
36ac0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
36ad0 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20  X,E,P,F,D)].**  
36ae0 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68 65          with the
36af0 20 73 61 6d 65 20 76 61 6c 75 65 73 20 66 6f 72   same values for
36b00 20 42 2c 20 58 2c 20 61 6e 64 20 45 2c 20 6f 76   B, X, and E, ov
36b10 65 72 72 69 64 65 20 70 72 69 6f 72 20 76 61 6c  erride prior val
36b20 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ues.**          
36b30 6f 66 20 50 2c 20 46 2c 20 61 6e 64 20 44 2e 0a  of P, F, and D..
36b40 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 39 7d 20 49  **.** {H16609} I
36b50 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
36b60 20 44 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63   D in [sqlite3_c
36b70 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
36b80 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
36b90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
36ba0 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 69 74  not NULL then it
36bb0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
36bc0 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 20  argument P when 
36bd0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
36be0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36bf0 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 62 79  on is dropped by
36c00 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b   SQLite..**.** {
36c10 48 31 36 36 31 32 7d 20 41 20 63 6f 6c 6c 61 74  H16612} A collat
36c20 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
36c30 64 72 6f 70 70 65 64 20 77 68 65 6e 20 69 74 20  dropped when it 
36c40 69 73 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a  is overloaded..*
36c50 2a 0a 2a 2a 20 7b 48 31 36 36 31 35 7d 20 41 20  *.** {H16615} A 
36c60 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36c70 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77 68  on is dropped wh
36c80 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
36c90 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20  connection.**   
36ca0 20 20 20 20 20 20 20 69 73 20 63 6c 6f 73 65 64         is closed
36cb0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
36cc0 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  close()]..**.** 
36cd0 7b 48 31 36 36 31 38 7d 20 54 68 65 20 70 6f 69  {H16618} The poi
36ce0 6e 74 65 72 20 50 20 69 6e 20 5b 73 71 6c 69 74  nter P in [sqlit
36cf0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36d00 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46  ion_v2(B,X,E,P,F
36d10 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,D)].**         
36d20 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
36d30 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
36d40 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
36d50 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20   comparison.**  
36d60 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e          function
36d70 20 46 20 66 6f 72 20 61 6c 6c 20 73 75 62 73 65   F for all subse
36d80 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
36d90 73 20 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b 48  s of F..**.** {H
36da0 31 36 36 32 31 7d 20 41 20 63 61 6c 6c 20 74 6f  16621} A call to
36db0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
36dc0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45  _collation(B,X,E
36dd0 2c 50 2c 46 29 5d 20 69 73 20 65 78 61 63 74 6c  ,P,F)] is exactl
36de0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  y.**          th
36df0 65 20 73 61 6d 65 20 61 73 20 61 20 63 61 6c 6c  e same as a call
36e00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
36e10 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
36e20 28 29 5d 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  ()] with.**     
36e30 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 70 61       the same pa
36e40 72 61 6d 65 74 65 72 73 20 61 6e 64 20 61 20 4e  rameters and a N
36e50 55 4c 4c 20 64 65 73 74 72 75 63 74 6f 72 2e 0a  ULL destructor..
36e60 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 34 7d 20 46  **.** {H16624} F
36e70 6f 6c 6c 6f 77 69 6e 67 20 61 20 5b 73 71 6c 69  ollowing a [sqli
36e80 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
36e90 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c  tion_v2(B,X,E,P,
36ea0 46 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  F,D)],.**       
36eb0 20 20 20 53 51 4c 69 74 65 20 75 73 65 73 20 74     SQLite uses t
36ec0 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75  he comparison fu
36ed0 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c  nction F for all
36ee0 20 74 65 78 74 20 63 6f 6d 70 61 72 69 73 6f 6e   text comparison
36ef0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 70 65  .**          ope
36f00 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 5b  rations on the [
36f10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36f20 69 6f 6e 5d 20 42 20 6f 6e 20 74 65 78 74 20 76  ion] B on text v
36f30 61 6c 75 65 73 20 74 68 61 74 0a 2a 2a 20 20 20  alues that.**   
36f40 20 20 20 20 20 20 20 75 73 65 20 74 68 65 20 63         use the c
36f50 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63  ollating sequenc
36f60 65 20 6e 61 6d 65 64 20 58 2e 0a 2a 2a 0a 2a 2a  e named X..**.**
36f70 20 7b 48 31 36 36 32 37 7d 20 54 68 65 20 5b 73   {H16627} The [s
36f80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36f90 6c 6c 61 74 69 6f 6e 31 36 28 42 2c 58 2c 45 2c  llation16(B,X,E,
36fa0 50 2c 46 29 5d 20 77 6f 72 6b 73 20 74 68 65 20  P,F)] works the 
36fb0 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
36fc0 20 61 73 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   as [sqlite3_cre
36fd0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c  ate_collation(B,
36fe0 58 2c 45 2c 50 2c 46 29 5d 20 65 78 63 65 70 74  X,E,P,F)] except
36ff0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20   that the.**    
37000 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20        collation 
37010 6e 61 6d 65 20 58 20 69 73 20 75 6e 64 65 72 73  name X is unders
37020 74 6f 6f 64 20 61 73 20 55 54 46 2d 31 36 20 69  tood as UTF-16 i
37030 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
37040 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
37050 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38  instead of UTF-8
37060 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 33 30 7d  ..**.** {H16630}
37070 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 63   When multiple c
37080 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69  omparison functi
37090 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ons are availabl
370a0 65 20 66 6f 72 20 74 68 65 20 73 61 6d 65 0a 2a  e for the same.*
370b0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61  *          colla
370c0 74 69 6e 67 20 73 65 71 75 65 6e 63 65 2c 20 53  ting sequence, S
370d0 51 4c 69 74 65 20 63 68 6f 6f 73 65 73 20 74 68  QLite chooses th
370e0 65 20 6f 6e 65 20 77 68 6f 73 65 20 74 65 78 74  e one whose text
370f0 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 20 20 20   encoding.**    
37100 20 20 20 20 20 20 72 65 71 75 69 72 65 73 20 74        requires t
37110 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
37120 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72  of conversion fr
37130 6f 6d 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a  om the default.*
37140 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20  *          text 
37150 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20  encoding of the 
37160 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74  database..*/.int
37170 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
37180 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c  collation(.  sql
37190 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
371a0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
371b0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
371c0 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
371d0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
371e0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
371f0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
37200 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
37210 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
37220 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  v2(.  sqlite3*, 
37230 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
37240 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
37250 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
37260 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
37270 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
37280 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
37290 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
372a0 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
372b0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
372c0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
372d0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
372e0 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  , .  const void 
372f0 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54  *zName,.  int eT
37300 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a  extRep, .  void*
37310 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
37320 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
37330 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
37340 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
37350 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
37360 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43  llation Needed C
37370 61 6c 6c 62 61 63 6b 73 20 7b 48 31 36 37 30 30  allbacks {H16700
37380 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20300>.**.**
37390 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67   To avoid having
373a0 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c   to register all
373b0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
373c0 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61  nces before a da
373d0 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65  tabase.** can be
373e0 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20   used, a single 
373f0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
37400 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
37410 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  red with the.** 
37420 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
37430 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63 61 6c 6c  tion] to be call
37440 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75  ed whenever an u
37450 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
37460 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69  on.** sequence i
37470 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  s required..**.*
37480 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f  * If the functio
37490 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  n is registered 
374a0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
374b0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
374c0 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65  ed() API,.** the
374d0 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74  n it is passed t
374e0 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65  he names of unde
374f0 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  fined collation 
37500 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72  sequences as str
37510 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20  ings.** encoded 
37520 69 6e 20 55 54 46 2d 38 2e 20 7b 48 31 36 37 30  in UTF-8. {H1670
37530 33 7d 20 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  3} If sqlite3_co
37540 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
37550 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74  () is used,.** t
37560 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73  he names are pas
37570 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  sed as UTF-16 in
37580 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20   machine native 
37590 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 41  byte order..** A
375a0 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20   call to either 
375b0 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65  function replace
375c0 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63  s any existing c
375d0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57  allback..**.** W
375e0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
375f0 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65   is invoked, the
37600 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
37610 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79  passed is a copy
37620 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  .** of the secon
37630 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
37640 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
37650 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73  needed() or.** s
37660 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
37670 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68  _needed16().  Th
37680 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
37690 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73  t is the databas
376a0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
376b0 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
376c0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
376d0 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53  SQLITE_UTF8], [S
376e0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a  QLITE_UTF16BE],.
376f0 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ** or [SQLITE_UT
37700 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69  F16LE], indicati
37710 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69  ng the most desi
37720 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68  rable form of th
37730 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  e collation.** s
37740 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e  equence function
37750 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20   required.  The 
37760 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
37770 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
37780 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20  the.** required 
37790 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
377a0 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  ce..**.** The ca
377b0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
377c0 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20  should register 
377d0 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c  the desired coll
377e0 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
377f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
37800 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  ollation()], [sq
37810 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
37820 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  lation16()], or.
37830 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
37840 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
37850 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
37860 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ANTS:.**.** {H16
37870 37 30 32 7d 20 41 20 73 75 63 63 65 73 73 66 75  702} A successfu
37880 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
37890 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
378a0 64 65 64 28 44 2c 50 2c 46 29 5d 0a 2a 2a 20 20  ded(D,P,F)].**  
378b0 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
378c0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
378d0 65 64 65 64 31 36 28 44 2c 50 2c 46 29 5d 20 63  eded16(D,P,F)] c
378e0 61 75 73 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  auses.**        
378f0 20 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20    the [database 
37900 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f  connection] D to
37910 20 69 6e 76 6f 6b 65 20 63 61 6c 6c 62 61 63 6b   invoke callback
37920 20 46 20 77 69 74 68 20 66 69 72 73 74 0a 2a 2a   F with first.**
37930 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65            parame
37940 74 65 72 20 50 20 77 68 65 6e 65 76 65 72 20 69  ter P whenever i
37950 74 20 6e 65 65 64 73 20 61 20 63 6f 6d 70 61 72  t needs a compar
37960 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 66 6f  ison function fo
37970 72 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r a.**          
37980 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e  collating sequen
37990 63 65 20 74 68 61 74 20 69 74 20 64 6f 65 73 20  ce that it does 
379a0 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f 75 74 2e 0a  not know about..
379b0 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 34 7d 20 45  **.** {H16704} E
379c0 61 63 68 20 73 75 63 63 65 73 73 66 75 6c 20 63  ach successful c
379d0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
379e0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
379f0 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ()] or.**       
37a00 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c     [sqlite3_coll
37a10 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
37a20 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 20  ] overrides the 
37a30 63 61 6c 6c 62 61 63 6b 20 72 65 67 69 73 74 65  callback registe
37a40 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
37a50 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
37a60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37a70 5d 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73  ] by prior calls
37a80 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 20 20   to either.**   
37a90 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
37aa0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 36 7d  ..**.** {H16706}
37ab0 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   The name of the
37ac0 20 72 65 71 75 65 73 74 65 64 20 63 6f 6c 6c 61   requested colla
37ad0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ting function pa
37ae0 73 73 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 20  ssed in the.**  
37af0 20 20 20 20 20 20 20 20 34 74 68 20 70 61 72 61          4th para
37b00 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
37b10 6c 62 61 63 6b 20 69 73 20 69 6e 20 55 54 46 2d  lback is in UTF-
37b20 38 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63  8 if the callbac
37b30 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 61  k.**          wa
37b40 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
37b50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ng [sqlite3_coll
37b60 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
37b70 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
37b80 69 73 20 69 6e 20 55 54 46 2d 31 36 20 6e 61 74  is in UTF-16 nat
37b90 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
37ba0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77  f the callback w
37bb0 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  as.**          r
37bc0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
37bd0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
37be0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
37bf0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
37c00 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
37c10 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
37c20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  void*, .  void(*
37c30 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
37c40 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
37c50 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e  nst char*).);.in
37c60 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
37c70 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20  ion_needed16(.  
37c80 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
37c90 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  d*,.  void(*)(vo
37ca0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
37cb0 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
37cc0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
37cd0 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79   Specify the key
37ce0 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65   for an encrypte
37cf0 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69  d database.  Thi
37d00 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  s routine should
37d10 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69   be.** called ri
37d20 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65  ght after sqlite
37d30 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_open()..**.** 
37d40 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
37d50 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
37d60 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
37d70 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
37d80 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
37d90 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
37da0 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  e3_key(.  sqlite
37db0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
37dc0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
37dd0 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
37de0 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
37df0 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
37e00 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65  ey     /* The ke
37e10 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
37e20 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e  hange the key on
37e30 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
37e40 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65  e.  If the curre
37e50 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e  nt database is n
37e60 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c  ot.** encrypted,
37e70 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
37e80 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20  ll encrypt it.  
37e90 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e  If pNew==0 or nN
37ea0 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61  ew==0, the.** da
37eb0 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70  tabase is decryp
37ec0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ted..**.** The c
37ed0 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
37ee0 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
37ef0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
37f00 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
37f10 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
37f20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
37f30 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
37f40 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
37f50 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
37f60 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
37f70 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
37f80 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
37f90 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
37fa0 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
37fb0 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e  CAPI3REF: Suspen
37fc0 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20  d Execution For 
37fd0 41 20 53 68 6f 72 74 20 54 69 6d 65 20 7b 48 31  A Short Time {H1
37fe0 30 35 33 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a  0530} <S40410>.*
37ff0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
38000 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f  _sleep() functio
38010 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72  n causes the cur
38020 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73  rent thread to s
38030 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
38040 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74  .** for at least
38050 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c   a number of mil
38060 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66  liseconds specif
38070 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d  ied in its param
38080 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  eter..**.** If t
38090 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
380a0 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70  tem does not sup
380b0 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65  port sleep reque
380c0 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c  sts with.** mill
380d0 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73  isecond time res
380e0 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  olution, then th
380f0 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72  e time will be r
38100 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20  ounded up to.** 
38110 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f  the nearest seco
38120 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  nd. The number o
38130 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  f milliseconds o
38140 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
38150 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72  .** requested fr
38160 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  om the operating
38170 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72   system is retur
38180 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ned..**.** SQLit
38190 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69  e implements thi
381a0 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63  s interface by c
381b0 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65  alling the xSlee
381c0 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  p().** method of
381d0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
381e0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
381f0 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  t..**.** INVARIA
38200 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35  NTS:.**.** {H105
38210 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  33} The [sqlite3
38220 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72  _sleep(M)] inter
38230 66 61 63 65 20 69 6e 76 6f 6b 65 73 20 74 68 65  face invokes the
38240 20 78 53 6c 65 65 70 0a 2a 2a 20 20 20 20 20 20   xSleep.**      
38250 20 20 20 20 6d 65 74 68 6f 64 20 6f 66 20 74 68      method of th
38260 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
38270 65 33 5f 76 66 73 7c 56 46 53 5d 20 69 6e 20 6f  e3_vfs|VFS] in o
38280 72 64 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  rder to.**      
38290 20 20 20 20 73 75 73 70 65 6e 64 20 65 78 65 63      suspend exec
382a0 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72  ution of the cur
382b0 72 65 6e 74 20 74 68 72 65 61 64 20 66 6f 72 20  rent thread for 
382c0 61 74 20 6c 65 61 73 74 0a 2a 2a 20 20 20 20 20  at least.**     
382d0 20 20 20 20 20 4d 20 6d 69 6c 6c 69 73 65 63 6f       M milliseco
382e0 6e 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35  nds..**.** {H105
382f0 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  36} The [sqlite3
38300 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72  _sleep(M)] inter
38310 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
38320 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20   number of.**   
38330 20 20 20 20 20 20 20 6d 69 6c 6c 69 73 65 63 6f         milliseco
38340 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74  nds of sleep act
38350 75 61 6c 6c 79 20 72 65 71 75 65 73 74 65 64 20  ually requested 
38360 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  of the operating
38370 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 79 73  .**          sys
38380 74 65 6d 2c 20 77 68 69 63 68 20 6d 69 67 68 74  tem, which might
38390 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
383a0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4d 2e  the parameter M.
383b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
383c0 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  sleep(int);../*.
383d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
383e0 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
383f0 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72  Holding Temporar
38400 79 20 46 69 6c 65 73 20 7b 48 31 30 33 31 30 7d  y Files {H10310}
38410 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20000>.**.** 
38420 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
38430 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
38440 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
38450 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
38460 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
38470 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
38480 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
38490 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
384a0 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
384b0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
384c0 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64  placed in that d
384d0 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68  irectory.  If th
384e0 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
384f0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
38500 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65  , then SQLite pe
38510 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20  rforms a search 
38520 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61  for an appropria
38530 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
38540 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a  file directory..
38550 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  **.** It is not 
38560 73 61 66 65 20 74 6f 20 6d 6f 64 69 66 79 20 74  safe to modify t
38570 68 69 73 20 76 61 72 69 61 62 6c 65 20 6f 6e 63  his variable onc
38580 65 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  e a [database co
38590 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 68 61 73  nnection].** has
385a0 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 20 49   been opened.  I
385b0 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68  t is intended th
385c0 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
385d0 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20   be set once.** 
385e0 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65  as part of proce
385f0 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
38600 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79  n and before any
38610 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
38620 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61  e.** routines ha
38630 76 65 20 62 65 65 6e 20 63 61 6c 6c 20 61 6e 64  ve been call and
38640 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
38650 64 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2f  d thereafter..*/
38660 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
38670 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d  har *sqlite3_tem
38680 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a  p_directory;../*
38690 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
386a0 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d  st For Auto-Comm
386b0 69 74 20 4d 6f 64 65 20 7b 48 31 32 39 33 30 7d  it Mode {H12930}
386c0 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 4b 45 59   <S60200>.** KEY
386d0 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d  WORDS: {autocomm
386e0 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54  it mode}.**.** T
386f0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
38700 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65  utocommit() inte
38710 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f  rface returns no
38720 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72  n-zero or.** zer
38730 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64  o if the given d
38740 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38750 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20  on is or is not 
38760 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  in autocommit mo
38770 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  de,.** respectiv
38780 65 6c 79 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74  ely.  Autocommit
38790 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64   mode is on by d
387a0 65 66 61 75 6c 74 2e 0a 2a 2a 20 41 75 74 6f 63  efault..** Autoc
387b0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69  ommit mode is di
387c0 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47  sabled by a [BEG
387d0 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  IN] statement..*
387e0 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  * Autocommit mod
387f0 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20  e is re-enabled 
38800 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72  by a [COMMIT] or
38810 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a   [ROLLBACK]..**.
38820 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69  ** If certain ki
38830 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63  nds of errors oc
38840 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65  cur on a stateme
38850 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74  nt within a mult
38860 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  i-statement.** t
38870 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f  ransaction (erro
38880 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51  rs including [SQ
38890 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c  LITE_FULL], [SQL
388a0 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b  ITE_IOERR],.** [
388b0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b  SQLITE_NOMEM], [
388c0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e  SQLITE_BUSY], an
388d0 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  d [SQLITE_INTERR
388e0 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a  UPT]) then the.*
388f0 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69  * transaction mi
38900 67 68 74 20 62 65 20 72 6f 6c 6c 65 64