/ Hex Artifact Content
Login

Artifact 0bd3a45823801389ac9e571aa71c0375b6ab2171:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f  rve to make mino
03c0: 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a 20  r changes if.** 
03d0: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20  experience from 
03e0: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64  use "in the wild
03f0: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63  " suggest such c
0400: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65  hanges are prude
0410: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66  nt..**.** The of
0420: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67  ficial C-languag
0430: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74  e API documentat
0440: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69  ion for SQLite i
0450: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f  s derived.** fro
0460: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68  m comments in th
0470: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66  is file.  This f
0480: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f  ile is the autho
0490: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a  ritative source.
04a0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65  ** on how SQLite
04b0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
04c0: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61  suppose to opera
04d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  te..**.** The na
04e0: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  me of this file 
04f0: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74  under configurat
0500: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69  ion management i
0510: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e  s "sqlite.h.in".
0520: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65  .** The makefile
0530: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f   makes some mino
0540: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69  r changes to thi
0550: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20  s file (such as 
0560: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65  inserting.** the
0570: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29   version number)
0580: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73   and changes its
0590: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65   name to "sqlite
05a0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20  3.h" as.** part 
05b0: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f  of the build pro
05c0: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23 29  cess..**.** @(#)
05d0: 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e 69   $Id: sqlite.h.i
05e0: 6e 2c 76 20 31 2e 33 37 35 20 32 30 30 38 2f 30  n,v 1.375 2008/0
05f0: 37 2f 32 33 20 31 33 3a 34 32 3a 32 36 20 6d 69  7/23 13:42:26 mi
0600: 68 61 69 6c 69 6d 20 45 78 70 20 24 0a 2a 2f 0a  hailim Exp $.*/.
0610: 23 69 66 6e 64 65 66 20 5f 53 51 4c 49 54 45 33  #ifndef _SQLITE3
0620: 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f 53 51 4c  _H_.#define _SQL
0630: 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c 75 64 65  ITE3_H_.#include
0640: 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20   <stdarg.h>     
0650: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68  /* Needed for th
0660: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20  e definition of 
0670: 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  va_list */../*.*
0680: 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63  * Make sure we c
0690: 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75  an call this stu
06a0: 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a  ff from C++..*/.
06b0: 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c  #ifdef __cpluspl
06c0: 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a  us.extern "C" {.
06d0: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41  #endif.../*.** A
06e0: 64 64 20 74 68 65 20 61 62 69 6c 69 74 79 20 74  dd the ability t
06f0: 6f 20 6f 76 65 72 72 69 64 65 20 27 65 78 74 65  o override 'exte
0700: 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  rn'.*/.#ifndef S
0710: 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64  QLITE_EXTERN.# d
0720: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54  efine SQLITE_EXT
0730: 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69  ERN extern.#endi
0740: 66 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20  f../*.** Ensure 
0750: 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65  these symbols we
0760: 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62  re not defined b
0770: 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20  y some previous 
0780: 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a  header file..*/.
0790: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45  #ifdef SQLITE_VE
07a0: 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51  RSION.# undef SQ
07b0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e  LITE_VERSION.#en
07c0: 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54  dif.#ifdef SQLIT
07d0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
07e0: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
07f0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0800: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
0810: 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
0820: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
0830: 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31 30  ion Numbers {H10
0840: 30 31 30 7d 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a  010}<S60100>.**.
0850: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45  ** The SQLITE_VE
0860: 52 53 49 4f 4e 20 61 6e 64 20 53 51 4c 49 54 45  RSION and SQLITE
0870: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0880: 23 64 65 66 69 6e 65 73 20 69 6e 0a 2a 2a 20 74  #defines in.** t
0890: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 66 69 6c  he sqlite3.h fil
08a0: 65 20 73 70 65 63 69 66 79 20 74 68 65 20 76 65  e specify the ve
08b0: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
08c0: 77 69 74 68 20 77 68 69 63 68 0a 2a 2a 20 74 68  with which.** th
08d0: 61 74 20 68 65 61 64 65 72 20 66 69 6c 65 20 69  at header file i
08e0: 73 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a  s associated..**
08f0: 0a 2a 2a 20 54 68 65 20 22 76 65 72 73 69 6f 6e  .** The "version
0900: 22 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 61  " of SQLite is a
0910: 20 73 74 72 69 6e 67 20 6f 66 20 74 68 65 20 66   string of the f
0920: 6f 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20  orm "X.Y.Z"..** 
0930: 54 68 65 20 70 68 72 61 73 65 20 22 61 6c 70 68  The phrase "alph
0940: 61 22 20 6f 72 20 22 62 65 74 61 22 20 6d 69 67  a" or "beta" mig
0950: 68 74 20 62 65 20 61 70 70 65 6e 64 65 64 20 61  ht be appended a
0960: 66 74 65 72 20 74 68 65 20 5a 2e 0a 2a 2a 20 54  fter the Z..** T
0970: 68 65 20 58 20 76 61 6c 75 65 20 69 73 20 6d 61  he X value is ma
0980: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0990: 65 72 20 61 6c 77 61 79 73 20 33 20 69 6e 20 53  er always 3 in S
09a0: 51 4c 69 74 65 33 2e 0a 2a 2a 20 54 68 65 20 58  QLite3..** The X
09b0: 20 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e   value only chan
09c0: 67 65 73 20 77 68 65 6e 20 62 61 63 6b 77 61 72  ges when backwar
09d0: 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
09e0: 20 69 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e   is.** broken an
09f0: 64 20 77 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e  d we intend to n
0a00: 65 76 65 72 20 62 72 65 61 6b 20 62 61 63 6b 77  ever break backw
0a10: 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
0a20: 74 79 2e 0a 2a 2a 20 54 68 65 20 59 20 76 61 6c  ty..** The Y val
0a30: 75 65 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20  ue is the minor 
0a40: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0a50: 6e 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20  nd only changes 
0a60: 77 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72  when.** there ar
0a70: 65 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20  e major feature 
0a80: 65 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61  enhancements tha
0a90: 74 20 61 72 65 20 66 6f 72 77 61 72 64 73 20 63  t are forwards c
0aa0: 6f 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74  ompatible.** but
0ab0: 20 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63   not backwards c
0ac0: 6f 6d 70 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68  ompatible..** Th
0ad0: 65 20 5a 20 76 61 6c 75 65 20 69 73 20 74 68 65  e Z value is the
0ae0: 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 20   release number 
0af0: 61 6e 64 20 69 73 20 69 6e 63 72 65 6d 65 6e 74  and is increment
0b00: 65 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20  ed with.** each 
0b10: 72 65 6c 65 61 73 65 20 62 75 74 20 72 65 73 65  release but rese
0b20: 74 73 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65  ts back to 0 whe
0b30: 6e 65 76 65 72 20 59 20 69 73 20 69 6e 63 72 65  never Y is incre
0b40: 6d 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65  mented..**.** Se
0b50: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
0b60: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 61  _libversion()] a
0b70: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  nd [sqlite3_libv
0b80: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d  ersion_number()]
0b90: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
0ba0: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 31  TS:.**.** {H1001
0bb0: 31 7d 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45  1} The SQLITE_VE
0bc0: 52 53 49 4f 4e 20 23 64 65 66 69 6e 65 20 69 6e  RSION #define in
0bd0: 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68   the sqlite3.h h
0be0: 65 61 64 65 72 20 66 69 6c 65 20 73 68 61 6c 6c  eader file shall
0bf0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 76 61  .**          eva
0c00: 6c 75 61 74 65 20 74 6f 20 61 20 73 74 72 69 6e  luate to a strin
0c10: 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20 69  g literal that i
0c20: 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 72  s the SQLite ver
0c30: 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  sion.**         
0c40: 20 77 69 74 68 20 77 68 69 63 68 20 74 68 65 20   with which the 
0c50: 68 65 61 64 65 72 20 66 69 6c 65 20 69 73 20 61  header file is a
0c60: 73 73 6f 63 69 61 74 65 64 2e 20 3c 53 36 30 31  ssociated. <S601
0c70: 30 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 31  00>.**.** {H1001
0c80: 34 7d 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45  4} The SQLITE_VE
0c90: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23 64 65  RSION_NUMBER #de
0ca0: 66 69 6e 65 20 73 68 61 6c 6c 20 72 65 73 6f 6c  fine shall resol
0cb0: 76 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  ve to an integer
0cc0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74  .**          wit
0cd0: 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a 31  h the value (X*1
0ce0: 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30 20  000000 + Y*1000 
0cf0: 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59 2c  + Z) where X, Y,
0d00: 20 61 6e 64 20 5a 0a 2a 2a 20 20 20 20 20 20 20   and Z.**       
0d10: 20 20 20 61 72 65 20 74 68 65 20 6d 61 6a 6f 72     are the major
0d20: 20 76 65 72 73 69 6f 6e 2c 20 6d 69 6e 6f 72 20   version, minor 
0d30: 76 65 72 73 69 6f 6e 2c 20 61 6e 64 20 72 65 6c  version, and rel
0d40: 65 61 73 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 20  ease number..** 
0d50: 20 20 20 20 20 20 20 20 20 3c 53 36 30 31 30 30           <S60100
0d60: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
0d70: 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20  ITE_VERSION     
0d80: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
0d90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
0da0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 20 2d 2d  RSION_NUMBER  --
0db0: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d  VERSION-NUMBER--
0dc0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0dd0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
0de0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0df0: 72 73 20 7b 48 31 30 30 32 30 7d 20 3c 53 36 30  rs {H10020} <S60
0e00: 31 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  100>.** KEYWORDS
0e10: 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  : sqlite3_versio
0e20: 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 65  n.**.** These fe
0e30: 61 74 75 72 65 73 20 70 72 6f 76 69 64 65 20 74  atures provide t
0e40: 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
0e50: 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49  ion as the [SQLI
0e60: 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 61  TE_VERSION].** a
0e70: 6e 64 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  nd [SQLITE_VERSI
0e80: 4f 4e 5f 4e 55 4d 42 45 52 5d 20 23 64 65 66 69  ON_NUMBER] #defi
0e90: 6e 65 73 20 69 6e 20 74 68 65 20 68 65 61 64 65  nes in the heade
0ea0: 72 2c 20 62 75 74 20 61 72 65 20 61 73 73 6f 63  r, but are assoc
0eb0: 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  iated.** with th
0ec0: 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61  e library instea
0ed0: 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72 20  d of the header 
0ee0: 66 69 6c 65 2e 20 20 43 61 75 74 69 6f 75 73 20  file.  Cautious 
0ef0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
0f00: 74 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 61 20 63  t.** include a c
0f10: 68 65 63 6b 20 69 6e 20 74 68 65 69 72 20 61 70  heck in their ap
0f20: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 76 65 72  plication to ver
0f30: 69 66 79 20 74 68 61 74 0a 2a 2a 20 73 71 6c 69  ify that.** sqli
0f40: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
0f50: 75 6d 62 65 72 28 29 20 61 6c 77 61 79 73 20 72  umber() always r
0f60: 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
0f70: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
0f80: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a 0a  ION_NUMBER]..**.
0f90: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  ** The sqlite3_l
0fa0: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
0fb0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
0fc0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
0fd0: 6e 20 61 73 20 69 73 0a 2a 2a 20 69 6e 20 74 68  n as is.** in th
0fe0: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
0ff0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1000: 61 6e 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69  ant.  The functi
1010: 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 0a 2a  on is provided.*
1020: 2a 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c  * for use in DLL
1030: 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72  s since DLL user
1040: 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74  s usually do not
1050: 20 68 61 76 65 20 64 69 72 65 63 74 20 61 63 63   have direct acc
1060: 65 73 73 20 74 6f 20 73 74 72 69 6e 67 0a 2a 2a  ess to string.**
1070: 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69   constants withi
1080: 6e 20 74 68 65 20 44 4c 4c 2e 0a 2a 2a 0a 2a 2a  n the DLL..**.**
1090: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
10a0: 2a 2a 20 7b 48 31 30 30 32 31 7d 20 54 68 65 20  ** {H10021} The 
10b0: 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  [sqlite3_libvers
10c0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 20 69 6e  ion_number()] in
10d0: 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65  terface shall re
10e0: 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
10f0: 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61   an integer equa
1100: 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 56 45 52  l to [SQLITE_VER
1110: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a  SION_NUMBER]..**
1120: 0a 2a 2a 20 7b 48 31 30 30 32 32 7d 20 54 68 65  .** {H10022} The
1130: 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f   [sqlite3_versio
1140: 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  n] string consta
1150: 6e 74 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e  nt shall contain
1160: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1170: 20 74 65 78 74 20 6f 66 20 74 68 65 20 5b 53 51   text of the [SQ
1180: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 73 74  LITE_VERSION] st
1190: 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  ring..**.** {H10
11a0: 30 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  023} The [sqlite
11b0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20  3_libversion()] 
11c0: 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72  function shall r
11d0: 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
11e0: 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74    a pointer to t
11f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73  he [sqlite3_vers
1200: 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  ion] string cons
1210: 74 61 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tant..*/.SQLITE_
1220: 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61  EXTERN const cha
1230: 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  r sqlite3_versio
1240: 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  n[];.const char 
1250: 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  *sqlite3_libvers
1260: 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ion(void);.int s
1270: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1280: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1290: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12a0: 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20   Test To See If 
12b0: 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54  The Library Is T
12c0: 68 72 65 61 64 73 61 66 65 20 7b 48 31 30 31 30  hreadsafe {H1010
12d0: 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a  0} <S60100>.**.*
12e0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
12f0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
1300: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
1310: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
1320: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1330: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
1340: 72 20 6d 61 63 72 6f 20 69 73 20 74 72 75 65 2c  r macro is true,
1350: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
1360: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
1370: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
1380: 2e 20 20 57 68 65 6e 20 74 68 61 74 20 6d 61 63  .  When that mac
1390: 72 6f 20 69 73 20 66 61 6c 73 65 2c 0a 2a 2a 20  ro is false,.** 
13a0: 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20  the mutexes are 
13b0: 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75  omitted.  Withou
13c0: 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69  t the mutexes, i
13d0: 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a  t is not safe.**
13e0: 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63   to use SQLite c
13f0: 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d  oncurrently from
1400: 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74   more than one t
1410: 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61  hread..**.** Ena
1420: 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e  bling mutexes in
1430: 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c  curs a measurabl
1440: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65  e performance pe
1450: 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20  nalty..** So if 
1460: 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f  speed is of utmo
1470: 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69  st importance, i
1480: 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f  t makes sense to
1490: 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20   disable.** the 
14a0: 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f  mutexes.  But fo
14b0: 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79  r maximum safety
14c0: 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64  , mutexes should
14d0: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20   be enabled..** 
14e0: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
14f0: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1500: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1510: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1520: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1530: 73 65 64 20 62 79 20 61 20 70 72 6f 67 72 61 6d  sed by a program
1540: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
1550: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
1560: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
1570: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
1580: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
1590: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
15a0: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
15b0: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
15c0: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
15d0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
15e0: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
15f0: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
1600: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
1610: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
1620: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1630: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
1640: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1650: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
1660: 54 48 52 45 41 44 53 41 46 45 3d 31 20 74 68 65  THREADSAFE=1 the
1670: 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e  n mutexes are en
1680: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
1690: 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66   but.** can be f
16a0: 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c  ully or partiall
16b0: 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67  y disabled using
16c0: 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
16d0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a  te3_config()].**
16e0: 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20   with the verbs 
16f0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
1700: 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53  INGLETHREAD], [S
1710: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
1720: 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72  TITHREAD],.** or
1730: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
1740: 4d 55 54 45 58 5d 2e 20 20 54 68 65 20 72 65 74  MUTEX].  The ret
1750: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
1760: 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73  s function shows
1770: 0a 2a 2a 20 6f 6e 6c 79 20 74 68 65 20 64 65 66  .** only the def
1780: 61 75 6c 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ault compile-tim
1790: 65 20 73 65 74 74 69 6e 67 2c 20 6e 6f 74 20 61  e setting, not a
17a0: 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e  ny run-time chan
17b0: 67 65 73 0a 2a 2a 20 74 6f 20 74 68 61 74 20 73  ges.** to that s
17c0: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e  etting..**.** IN
17d0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
17e0: 7b 48 31 30 31 30 31 7d 20 54 68 65 20 5b 73 71  {H10101} The [sq
17f0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
1800: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61  ()] function sha
1810: 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 7a 65 72  ll return nonzer
1820: 6f 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  o if.**         
1830: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1840: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 69 74  iled with the it
1850: 73 20 6d 75 74 65 78 65 73 20 65 6e 61 62 6c 65  s mutexes enable
1860: 64 20 62 79 20 64 65 66 61 75 6c 74 0a 2a 2a 20  d by default.** 
1870: 20 20 20 20 20 20 20 20 20 6f 72 20 7a 65 72 6f           or zero
1880: 20 69 66 20 53 51 4c 69 74 65 20 77 61 73 20 63   if SQLite was c
1890: 6f 6d 70 69 6c 65 64 20 73 75 63 68 20 74 68 61  ompiled such tha
18a0: 74 20 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a  t mutexes are.**
18b0: 20 20 20 20 20 20 20 20 20 20 70 65 72 6d 61 6e            perman
18c0: 65 6e 74 6c 79 20 64 69 73 61 62 6c 65 64 2e 0a  ently disabled..
18d0: 2a 2a 0a 2a 2a 20 7b 48 31 30 31 30 32 7d 20 54  **.** {H10102} T
18e0: 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
18f0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
1900: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
1910: 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  function.**     
1920: 20 20 20 20 20 73 68 61 6c 6c 20 6e 6f 74 20 63       shall not c
1930: 68 61 6e 67 65 20 77 68 65 6e 20 6d 75 74 65 78  hange when mutex
1940: 20 73 65 74 74 69 6e 67 20 61 72 65 20 6d 6f 64   setting are mod
1950: 69 66 69 65 64 20 61 74 0a 2a 2a 20 20 20 20 20  ified at.**     
1960: 20 20 20 20 20 72 75 6e 74 69 6d 65 20 75 73 69       runtime usi
1970: 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
1980: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
1990: 61 63 65 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20  ace and .**     
19a0: 20 20 20 20 20 65 73 70 65 63 69 61 6c 6c 79 20       especially 
19b0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
19c0: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
19d0: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  ,.**          [S
19e0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
19f0: 54 49 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49  TITHREAD], [SQLI
1a00: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
1a10: 49 5a 45 44 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  IZED],.**       
1a20: 20 20 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43     and [SQLITE_C
1a30: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 76 65 72  ONFIG_MUTEX] ver
1a40: 62 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  bs..*/.int sqlit
1a50: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f  e3_threadsafe(vo
1a60: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
1a70: 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
1a80: 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65  onnection Handle
1a90: 20 7b 48 31 32 30 30 30 7d 20 3c 53 34 30 32 30   {H12000} <S4020
1aa0: 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
1ab0: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
1ac0: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
1ad0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
1ae0: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
1af0: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
1b00: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
1b10: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
1b20: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
1b30: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
1b40: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
1b50: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
1b60: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
1b70: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
1b80: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
1b90: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
1ba0: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
1bb0: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
1bc0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
1bd0: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
1be0: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
1bf0: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
1c00: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
1c10: 2a 20 69 73 20 69 74 73 20 64 65 73 74 72 75 63  * is its destruc
1c20: 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65 20  tor.  There are 
1c30: 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72  many other inter
1c40: 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a  faces (such as.*
1c50: 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1c60: 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
1c70: 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
1c80: 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  on()], and.** [s
1c90: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1ca0: 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62  out()] to name b
1cb0: 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61  ut three) that a
1cc0: 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e  re methods on an
1cd0: 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65  .** sqlite3 obje
1ce0: 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ct..*/.typedef s
1cf0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71  truct sqlite3 sq
1d00: 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lite3;../*.** CA
1d10: 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49  PI3REF: 64-Bit I
1d20: 6e 74 65 67 65 72 20 54 79 70 65 73 20 7b 48 31  nteger Types {H1
1d30: 30 32 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a 2a  0200} <S10110>.*
1d40: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
1d50: 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f  te_int64 sqlite_
1d60: 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63  uint64.**.** Bec
1d70: 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f  ause there is no
1d80: 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20   cross-platform 
1d90: 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 36  way to specify 6
1da0: 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 79  4-bit integer ty
1db0: 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  pes.** SQLite in
1dc0: 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 20  cludes typedefs 
1dd0: 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65  for 64-bit signe
1de0: 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69  d and unsigned i
1df0: 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54  ntegers..**.** T
1e00: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  he sqlite3_int64
1e10: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e   and sqlite3_uin
1e20: 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65 66  t64 are the pref
1e30: 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69 6e  erred type defin
1e40: 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73  itions..** The s
1e50: 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20  qlite_int64 and 
1e60: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79  sqlite_uint64 ty
1e70: 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 65  pes are supporte
1e80: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a  d for backwards.
1e90: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
1ea0: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   only..**.** INV
1eb0: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
1ec0: 48 31 30 32 30 31 7d 20 54 68 65 20 5b 73 71 6c  H10201} The [sql
1ed0: 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e 64 20 5b  ite_int64] and [
1ee0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d 20 74  sqlite3_int64] t
1ef0: 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63 69 66  ype shall specif
1f00: 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  y.**          a 
1f10: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
1f20: 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  teger..**.** {H1
1f30: 30 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  0202} The [sqlit
1f40: 65 5f 75 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73  e_uint64] and [s
1f50: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 5d 20 74  qlite3_uint64] t
1f60: 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63 69 66  ype shall specif
1f70: 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  y.**          a 
1f80: 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  64-bit unsigned 
1f90: 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 66 64  integer..*/.#ifd
1fa0: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
1fb0: 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53  TYPE.  typedef S
1fc0: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
1fd0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
1fe0: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
1ff0: 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  d SQLITE_INT64_T
2000: 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  YPE sqlite_uint6
2010: 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  4;.#elif defined
2020: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
2030: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
2040: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
2050: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
2060: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
2070: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
2080: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2090: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
20a0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
20b0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
20c0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
20d0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
20e0: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
20f0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2100: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
2110: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
2120: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
2130: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
2140: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
2150: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
2160: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
2170: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
2180: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
2190: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
21a0: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23  ting-point..*/.#
21b0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
21c0: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
21d0: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
21e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
21f0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2200: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
2210: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
2220: 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d 20 3c 53  tion {H12010} <S
2230: 33 30 31 30 30 3e 3c 53 34 30 32 30 30 3e 0a 2a  30100><S40200>.*
2240: 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
2250: 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75 63  e is the destruc
2260: 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  tor for the [sql
2270: 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  ite3] object..**
2280: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
2290: 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33   should [sqlite3
22a0: 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
22b0: 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61  lize] all [prepa
22c0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a  red statements].
22d0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
22e0: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f  blob_close | clo
22f0: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61  se] all [BLOB ha
2300: 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74 65  ndles] associate
2310: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 73  d with.** the [s
2320: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70  qlite3] object p
2330: 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69  rior to attempti
2340: 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20  ng to close the 
2350: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65 20 5b  object..** The [
2360: 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
2370: 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  t()] interface c
2380: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 6f  an be used to lo
2390: 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70 72 65  cate all.** [pre
23a0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
23b0: 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  ] associated wit
23c0: 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
23d0: 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64 65 73  nnection] if des
23e0: 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63 61 6c  ired..** Typical
23f0: 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f 6f 6b   code might look
2400: 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
2410: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
2420: 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  re>.** sqlite3_s
2430: 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a 20 77  tmt *pStmt;.** w
2440: 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d 20 73  hile( (pStmt = s
2450: 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
2460: 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b 0a 2a  (db, 0))!=0 ){.*
2470: 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c 69 74  * &nbsp;   sqlit
2480: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53 74 6d  e3_finalize(pStm
2490: 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f 70 72  t);.** }.** </pr
24a0: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
24b0: 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  **.** If [sqlite
24c0: 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e  3_close()] is in
24d0: 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72  voked while a tr
24e0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65  ansaction is ope
24f0: 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61  n,.** the transa
2500: 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74  ction is automat
2510: 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
2520: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ck..**.** INVARI
2530: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
2540: 30 31 31 7d 20 41 20 73 75 63 63 65 73 73 66 75  011} A successfu
2550: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
2560: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73 68 61  e3_close(C)] sha
2570: 6c 6c 20 64 65 73 74 72 6f 79 20 74 68 65 0a 2a  ll destroy the.*
2580: 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
2590: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
25a0: 20 6f 62 6a 65 63 74 20 43 2e 0a 2a 2a 0a 2a 2a   object C..**.**
25b0: 20 7b 48 31 32 30 31 32 7d 20 41 20 73 75 63 63   {H12012} A succ
25c0: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
25d0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
25e0: 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 53  ] shall return S
25f0: 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20  QLITE_OK..**.** 
2600: 7b 48 31 32 30 31 33 7d 20 41 20 73 75 63 63 65  {H12013} A succe
2610: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
2620: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d  qlite3_close(C)]
2630: 20 73 68 61 6c 6c 20 72 65 6c 65 61 73 65 20 61   shall release a
2640: 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  ll.**          m
2650: 65 6d 6f 72 79 20 61 6e 64 20 73 79 73 74 65 6d  emory and system
2660: 20 72 65 73 6f 75 72 63 65 73 20 61 73 73 6f 63   resources assoc
2670: 69 61 74 65 64 20 77 69 74 68 20 5b 64 61 74 61  iated with [data
2680: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2690: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 2e 0a  .**          C..
26a0: 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 34 7d 20 41  **.** {H12014} A
26b0: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
26c0: 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6f 6e 20 61  3_close(C)] on a
26d0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
26e0: 63 74 69 6f 6e 5d 20 43 20 74 68 61 74 0a 2a 2a  ction] C that.**
26f0: 20 20 20 20 20 20 20 20 20 20 68 61 73 20 6f 6e            has on
2700: 65 20 6f 72 20 6d 6f 72 65 20 6f 70 65 6e 20 5b  e or more open [
2710: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2720: 6e 74 73 5d 20 73 68 61 6c 6c 20 66 61 69 6c 20  nts] shall fail 
2730: 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  with.**         
2740: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59   an [SQLITE_BUSY
2750: 5d 20 65 72 72 6f 72 20 63 6f 64 65 2e 0a 2a 2a  ] error code..**
2760: 0a 2a 2a 20 7b 48 31 32 30 31 35 7d 20 41 20 63  .** {H12015} A c
2770: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2780: 63 6c 6f 73 65 28 43 29 5d 20 77 68 65 72 65 20  close(C)] where 
2790: 43 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  C is a NULL poin
27a0: 74 65 72 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20  ter shall.**    
27b0: 20 20 20 20 20 20 72 65 74 75 72 6e 20 53 51 4c        return SQL
27c0: 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ITE_OK..**.** {H
27d0: 31 32 30 31 39 7d 20 57 68 65 6e 20 5b 73 71 6c  12019} When [sql
27e0: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 69  ite3_close(C)] i
27f0: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 5b  s invoked on a [
2800: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2810: 69 6f 6e 5d 20 43 0a 2a 2a 20 20 20 20 20 20 20  ion] C.**       
2820: 20 20 20 74 68 61 74 20 68 61 73 20 61 20 70 65     that has a pe
2830: 6e 64 69 6e 67 20 74 72 61 6e 73 61 63 74 69 6f  nding transactio
2840: 6e 2c 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  n, the transacti
2850: 6f 6e 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20  on shall be.**  
2860: 20 20 20 20 20 20 20 20 72 6f 6c 6c 65 64 20 62          rolled b
2870: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  ack..**.** ASSUM
2880: 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
2890: 31 32 30 31 36 7d 20 54 68 65 20 43 20 70 61 72  12016} The C par
28a0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
28b0: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75 73  e3_close(C)] mus
28c0: 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55  t be either a NU
28d0: 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  LL.**          p
28e0: 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71  ointer or an [sq
28f0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f  lite3] object po
2900: 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a  inter obtained.*
2910: 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20  *          from 
2920: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
2930: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
2940: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  6()], or.**     
2950: 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70       [sqlite3_op
2960: 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f  en_v2()], and no
2970: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f  t previously clo
2980: 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  sed..*/.int sqli
2990: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
29a0: 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  3 *);../*.** The
29b0: 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c   type for a call
29c0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  back function..*
29d0: 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79  * This is legacy
29e0: 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e   and deprecated.
29f0: 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64    It is included
2a00: 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a   for historical.
2a10: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
2a20: 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75   and is not docu
2a30: 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64  mented..*/.typed
2a40: 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33  ef int (*sqlite3
2a50: 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a  _callback)(void*
2a60: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61  ,int,char**, cha
2a70: 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  r**);../*.** CAP
2a80: 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20  I3REF: One-Step 
2a90: 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20  Query Execution 
2aa0: 49 6e 74 65 72 66 61 63 65 20 7b 48 31 32 31 30  Interface {H1210
2ab0: 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a  0} <S10000>.**.*
2ac0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78  * The sqlite3_ex
2ad0: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ec() interface i
2ae0: 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 74 20 77  s a convenient w
2af0: 61 79 20 6f 66 20 72 75 6e 6e 69 6e 67 20 6f 6e  ay of running on
2b00: 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 53 51 4c  e or more.** SQL
2b10: 20 73 74 61 74 65 6d 65 6e 74 73 20 77 69 74 68   statements with
2b20: 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 77 72  out having to wr
2b30: 69 74 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63  ite a lot of C c
2b40: 6f 64 65 2e 20 20 54 68 65 20 55 54 46 2d 38 20  ode.  The UTF-8 
2b50: 65 6e 63 6f 64 65 64 0a 2a 2a 20 53 51 4c 20 73  encoded.** SQL s
2b60: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 70 61  tatements are pa
2b70: 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 20 73  ssed in as the s
2b80: 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2b90: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
2ba0: 29 2e 0a 2a 2a 20 54 68 65 20 73 74 61 74 65 6d  )..** The statem
2bb0: 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74  ents are evaluat
2bc0: 65 64 20 6f 6e 65 20 62 79 20 6f 6e 65 20 75 6e  ed one by one un
2bd0: 74 69 6c 20 65 69 74 68 65 72 20 61 6e 20 65 72  til either an er
2be0: 72 6f 72 20 6f 72 0a 2a 2a 20 61 6e 20 69 6e 74  ror or.** an int
2bf0: 65 72 72 75 70 74 20 69 73 20 65 6e 63 6f 75 6e  errupt is encoun
2c00: 74 65 72 65 64 2c 20 6f 72 20 75 6e 74 69 6c 20  tered, or until 
2c10: 74 68 65 79 20 61 72 65 20 61 6c 6c 20 64 6f 6e  they are all don
2c20: 65 2e 20 20 54 68 65 20 33 72 64 20 70 61 72 61  e.  The 3rd para
2c30: 6d 65 74 65 72 0a 2a 2a 20 69 73 20 61 6e 20 6f  meter.** is an o
2c40: 70 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b  ptional callback
2c50: 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
2c60: 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72   once for each r
2c70: 6f 77 20 6f 66 20 61 6e 79 20 71 75 65 72 79 0a  ow of any query.
2c80: 2a 2a 20 72 65 73 75 6c 74 73 20 70 72 6f 64 75  ** results produ
2c90: 63 65 64 20 62 79 20 74 68 65 20 53 51 4c 20 73  ced by the SQL s
2ca0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 65 20  tatements.  The 
2cb0: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 65  5th parameter te
2cc0: 6c 6c 73 20 77 68 65 72 65 0a 2a 2a 20 74 6f 20  lls where.** to 
2cd0: 77 72 69 74 65 20 61 6e 79 20 65 72 72 6f 72 20  write any error 
2ce0: 6d 65 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a 2a 20  messages..**.** 
2cf0: 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  The error messag
2d00: 65 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68  e passed back th
2d10: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
2d20: 72 61 6d 65 74 65 72 20 69 73 20 68 65 6c 64 0a  rameter is held.
2d30: 2a 2a 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ** in memory obt
2d40: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2d50: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
2d60: 54 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72  To avoid a memor
2d70: 79 20 6c 65 61 6b 2c 0a 2a 2a 20 74 68 65 20 63  y leak,.** the c
2d80: 61 6c 6c 69 6e 67 20 61 70 70 6c 69 63 61 74 69  alling applicati
2d90: 6f 6e 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 5b  on should call [
2da0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
2db0: 6f 6e 20 61 6e 79 20 65 72 72 6f 72 0a 2a 2a 20  on any error.** 
2dc0: 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e 65 64  message returned
2dd0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
2de0: 20 70 61 72 61 6d 65 74 65 72 20 77 68 65 6e 20   parameter when 
2df0: 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
2e00: 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 65 72 72  using.** the err
2e10: 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
2e20: 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
2e30: 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 32 6e  tement in the 2n
2e40: 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  d parameter is N
2e50: 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20  ULL or an empty 
2e60: 73 74 72 69 6e 67 0a 2a 2a 20 6f 72 20 61 20 73  string.** or a s
2e70: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
2e80: 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65   only whitespace
2e90: 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 2c 20 74   and comments, t
2ea0: 68 65 6e 20 6e 6f 20 53 51 4c 0a 2a 2a 20 73 74  hen no SQL.** st
2eb0: 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61  atements are eva
2ec0: 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64  luated and the d
2ed0: 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 20 63  atabase is not c
2ee0: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  hanged..**.** Th
2ef0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
2f00: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d   interface is im
2f10: 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 74 65 72  plemented in ter
2f20: 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ms of.** [sqlite
2f30: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2f40: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2f50: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
2f60: 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20  finalize()]..** 
2f70: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
2f80: 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
2f90: 6e 6f 74 68 69 6e 67 20 74 6f 20 74 68 65 20 64  nothing to the d
2fa0: 61 74 61 62 61 73 65 20 74 68 61 74 20 63 61 6e  atabase that can
2fb0: 6e 6f 74 20 62 65 20 64 6f 6e 65 0a 2a 2a 20 62  not be done.** b
2fc0: 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
2fd0: 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
2fe0: 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20  e3_step()], and 
2ff0: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
3000: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  e()]..**.** INVA
3010: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
3020: 31 32 31 30 31 7d 20 41 20 73 75 63 63 65 73 73  12101} A success
3030: 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
3040: 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  f [sqlite3_exec(
3050: 44 2c 53 2c 43 2c 41 2c 45 29 5d 0a 2a 2a 20 20  D,S,C,A,E)].**  
3060: 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 73 65          shall se
3070: 71 75 65 6e 74 69 61 6c 6c 79 20 65 76 61 6c 75  quentially evalu
3080: 61 74 65 20 61 6c 6c 20 6f 66 20 74 68 65 20 55  ate all of the U
3090: 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a  TF-8 encoded,.**
30a0: 20 20 20 20 20 20 20 20 20 20 73 65 6d 69 63 6f            semico
30b0: 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
30c0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
30d0: 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
30e0: 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
30f0: 73 74 72 69 6e 67 20 53 20 77 69 74 68 69 6e 20  string S within 
3100: 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74  the context of t
3110: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
3120: 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
3130: 2a 20 7b 48 31 32 31 30 32 7d 20 49 66 20 74 68  * {H12102} If th
3140: 65 20 53 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e S parameter to
3150: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44   [sqlite3_exec(D
3160: 2c 53 2c 43 2c 41 2c 45 29 5d 20 69 73 20 4e 55  ,S,C,A,E)] is NU
3170: 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  LL then.**      
3180: 20 20 20 20 74 68 65 20 61 63 74 69 6f 6e 73 20      the actions 
3190: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  of the interface
31a0: 20 73 68 61 6c 6c 20 62 65 20 74 68 65 20 73 61   shall be the sa
31b0: 6d 65 20 61 73 20 69 66 20 74 68 65 0a 2a 2a 20  me as if the.** 
31c0: 20 20 20 20 20 20 20 20 20 53 20 70 61 72 61 6d           S param
31d0: 65 74 65 72 20 77 65 72 65 20 61 6e 20 65 6d 70  eter were an emp
31e0: 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ty string..**.**
31f0: 20 7b 48 31 32 31 30 34 7d 20 54 68 65 20 72 65   {H12104} The re
3200: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73  turn value of [s
3210: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73  qlite3_exec()] s
3220: 68 61 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f  hall be [SQLITE_
3230: 4f 4b 5d 20 69 66 20 61 6c 6c 0a 2a 2a 20 20 20  OK] if all.**   
3240: 20 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65         SQL state
3250: 6d 65 6e 74 73 20 72 75 6e 20 73 75 63 63 65 73  ments run succes
3260: 73 66 75 6c 6c 79 20 61 6e 64 20 74 6f 20 63 6f  sfully and to co
3270: 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
3280: 7b 48 31 32 31 30 35 7d 20 54 68 65 20 72 65 74  {H12105} The ret
3290: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  urn value of [sq
32a0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68  lite3_exec()] sh
32b0: 61 6c 6c 20 62 65 20 61 6e 20 61 70 70 72 6f 70  all be an approp
32c0: 72 69 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20  riate.**        
32d0: 20 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f    non-zero [erro
32e0: 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 20 53  r code] if any S
32f0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69  QL statement fai
3300: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30  ls..**.** {H1210
3310: 37 7d 20 49 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  7} If one or mor
3320: 65 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61  e of the SQL sta
3330: 74 65 6d 65 6e 74 73 20 68 61 6e 64 65 64 20 74  tements handed t
3340: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
3350: 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  )].**          r
3360: 65 74 75 72 6e 20 72 65 73 75 6c 74 73 20 61 6e  eturn results an
3370: 64 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  d the 3rd parame
3380: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ter is not NULL,
3390: 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
33a0: 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66    the callback f
33b0: 75 6e 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65  unction specifie
33c0: 64 20 62 79 20 74 68 65 20 33 72 64 20 70 61 72  d by the 3rd par
33d0: 61 6d 65 74 65 72 20 73 68 61 6c 6c 20 62 65 0a  ameter shall be.
33e0: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f  **          invo
33f0: 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  ked once for eac
3400: 68 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e  h row of result.
3410: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 30 7d 20  .**.** {H12110} 
3420: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
3430: 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65  returns a non-ze
3440: 72 6f 20 76 61 6c 75 65 20 74 68 65 6e 20 5b 73  ro value then [s
3450: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a  qlite3_exec()].*
3460: 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c  *          shall
3470: 20 61 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   abort the SQL s
3480: 74 61 74 65 6d 65 6e 74 20 69 74 20 69 73 20 63  tatement it is c
3490: 75 72 72 65 6e 74 6c 79 20 65 76 61 6c 75 61 74  urrently evaluat
34a0: 69 6e 67 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ing,.**         
34b0: 20 73 6b 69 70 20 61 6c 6c 20 73 75 62 73 65 71   skip all subseq
34c0: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
34d0: 6e 74 73 2c 20 61 6e 64 20 72 65 74 75 72 6e 20  nts, and return 
34e0: 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a  [SQLITE_ABORT]..
34f0: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 33 7d 20 54  **.** {H12113} T
3500: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  he [sqlite3_exec
3510: 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c  ()] routine shal
3520: 6c 20 70 61 73 73 20 69 74 73 20 34 74 68 20 70  l pass its 4th p
3530: 61 72 61 6d 65 74 65 72 20 74 68 72 6f 75 67 68  arameter through
3540: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20  .**          as 
3550: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3560: 72 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  r of the callbac
3570: 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 36  k..**.** {H12116
3580: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  } The [sqlite3_e
3590: 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73  xec()] routine s
35a0: 68 61 6c 6c 20 73 65 74 20 74 68 65 20 32 6e 64  hall set the 2nd
35b0: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74   parameter of it
35c0: 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  s.**          ca
35d0: 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 74 68 65  llback to be the
35e0: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
35f0: 6e 73 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  ns in the curren
3600: 74 20 72 6f 77 20 6f 66 0a 2a 2a 20 20 20 20 20  t row of.**     
3610: 20 20 20 20 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a       result..**.
3620: 2a 2a 20 7b 48 31 32 31 31 39 7d 20 54 68 65 20  ** {H12119} The 
3630: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3640: 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73   routine shall s
3650: 65 74 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  et the 3rd param
3660: 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20  eter of its.**  
3670: 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b          callback
3680: 20 74 6f 20 62 65 20 61 6e 20 61 72 72 61 79 20   to be an array 
3690: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
36a0: 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74  trings holding t
36b0: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  he.**          v
36c0: 61 6c 75 65 73 20 66 6f 72 20 65 61 63 68 20 63  alues for each c
36d0: 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
36e0: 72 65 6e 74 20 72 65 73 75 6c 74 20 73 65 74 20  rent result set 
36f0: 72 6f 77 20 61 73 0a 2a 2a 20 20 20 20 20 20 20  row as.**       
3700: 20 20 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d     obtained from
3710: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
3720: 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
3730: 7b 48 31 32 31 32 32 7d 20 54 68 65 20 5b 73 71  {H12122} The [sq
3740: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f  lite3_exec()] ro
3750: 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20  utine shall set 
3760: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
3770: 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20  r of its.**     
3780: 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f       callback to
3790: 20 62 65 20 61 6e 20 61 72 72 61 79 20 6f 66 20   be an array of 
37a0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
37b0: 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a  ngs holding the.
37c0: 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65  **          name
37d0: 73 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  s of result colu
37e0: 6d 6e 73 20 61 73 20 6f 62 74 61 69 6e 65 64 20  mns as obtained 
37f0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
3800: 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a  lumn_name()]..**
3810: 0a 2a 2a 20 7b 48 31 32 31 32 35 7d 20 49 66 20  .** {H12125} If 
3820: 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
3830: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78  r to [sqlite3_ex
3840: 65 63 28 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68  ec()] is NULL th
3850: 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  en.**          [
3860: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
3870: 73 68 61 6c 6c 20 73 69 6c 65 6e 74 6c 79 20 64  shall silently d
3880: 69 73 63 61 72 64 20 71 75 65 72 79 20 72 65 73  iscard query res
3890: 75 6c 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ults..**.** {H12
38a0: 31 33 31 7d 20 49 66 20 61 6e 20 65 72 72 6f 72  131} If an error
38b0: 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 70 61   occurs while pa
38c0: 72 73 69 6e 67 20 6f 72 20 65 76 61 6c 75 61 74  rsing or evaluat
38d0: 69 6e 67 20 61 6e 79 20 6f 66 20 74 68 65 20 53  ing any of the S
38e0: 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  QL.**          s
38f0: 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
3900: 20 53 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20   S parameter of 
3910: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c  [sqlite3_exec(D,
3920: 53 2c 43 2c 41 2c 45 29 5d 20 61 6e 64 20 69 66  S,C,A,E)] and if
3930: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
3940: 20 45 20 70 61 72 61 6d 65 74 65 72 20 69 73 20   E parameter is 
3950: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b  not NULL, then [
3960: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
3970: 73 68 61 6c 6c 20 73 74 6f 72 65 0a 2a 2a 20 20  shall store.**  
3980: 20 20 20 20 20 20 20 20 69 6e 20 2a 45 20 61 6e          in *E an
3990: 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72   appropriate err
39a0: 6f 72 20 6d 65 73 73 61 67 65 20 77 72 69 74 74  or message writt
39b0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
39c0: 62 74 61 69 6e 65 64 0a 2a 2a 20 20 20 20 20 20  btained.**      
39d0: 20 20 20 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65      from [sqlite
39e0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a  3_malloc()]..**.
39f0: 2a 2a 20 7b 48 31 32 31 33 34 7d 20 54 68 65 20  ** {H12134} The 
3a00: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c  [sqlite3_exec(D,
3a10: 53 2c 43 2c 41 2c 45 29 5d 20 72 6f 75 74 69 6e  S,C,A,E)] routin
3a20: 65 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20  e shall set the 
3a30: 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20  value of.**     
3a40: 20 20 20 20 20 2a 45 20 74 6f 20 4e 55 4c 4c 20       *E to NULL 
3a50: 69 66 20 45 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  if E is not NULL
3a60: 20 61 6e 64 20 74 68 65 72 65 20 61 72 65 20 6e   and there are n
3a70: 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20  o errors..**.** 
3a80: 7b 48 31 32 31 33 37 7d 20 54 68 65 20 5b 73 71  {H12137} The [sq
3a90: 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43  lite3_exec(D,S,C
3aa0: 2c 41 2c 45 29 5d 20 66 75 6e 63 74 69 6f 6e 20  ,A,E)] function 
3ab0: 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 5b 65  shall set the [e
3ac0: 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 20 20  rror code].**   
3ad0: 20 20 20 20 20 20 20 61 6e 64 20 6d 65 73 73 61         and messa
3ae0: 67 65 20 61 63 63 65 73 73 69 62 6c 65 20 76 69  ge accessible vi
3af0: 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  a [sqlite3_errco
3b00: 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  de()],.**       
3b10: 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d     [sqlite3_errm
3b20: 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  sg()], and [sqli
3b30: 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e  te3_errmsg16()].
3b40: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 38 7d 20  .**.** {H12138} 
3b50: 49 66 20 74 68 65 20 53 20 70 61 72 61 6d 65 74  If the S paramet
3b60: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  er to [sqlite3_e
3b70: 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20  xec(D,S,C,A,E)] 
3b80: 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 0a 2a 2a  is NULL or an.**
3b90: 20 20 20 20 20 20 20 20 20 20 65 6d 70 74 79 20            empty 
3ba0: 73 74 72 69 6e 67 20 6f 72 20 63 6f 6e 74 61 69  string or contai
3bb0: 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72  ns nothing other
3bc0: 20 74 68 61 6e 20 77 68 69 74 65 73 70 61 63 65   than whitespace
3bd0: 2c 20 63 6f 6d 6d 65 6e 74 73 2c 0a 2a 2a 20 20  , comments,.**  
3be0: 20 20 20 20 20 20 20 20 61 6e 64 2f 6f 72 20 73          and/or s
3bf0: 65 6d 69 63 6f 6c 6f 6e 73 2c 20 74 68 65 6e 20  emicolons, then 
3c00: 72 65 73 75 6c 74 73 20 6f 66 20 5b 73 71 6c 69  results of [sqli
3c10: 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a  te3_errcode()],.
3c20: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
3c30: 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20  ite3_errmsg()], 
3c40: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
3c50: 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20  msg16()].**     
3c60: 20 20 20 20 20 73 68 61 6c 6c 20 72 65 73 65 74       shall reset
3c70: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 6e 6f 20   to indicate no 
3c80: 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 53  errors..**.** AS
3c90: 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  SUMPTIONS:.**.**
3ca0: 20 7b 41 31 32 31 34 31 7d 20 54 68 65 20 66 69   {A12141} The fi
3cb0: 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
3cc0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3cd0: 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 76 61 6c  ] must be an val
3ce0: 69 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20  id and open.**  
3cf0: 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
3d00: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
3d10: 2a 0a 2a 2a 20 7b 41 31 32 31 34 32 7d 20 54 68  *.** {A12142} Th
3d20: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
3d30: 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62  ction must not b
3d40: 65 20 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a  e closed while.*
3d50: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
3d60: 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72  te3_exec()] is r
3d70: 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41  unning..**.** {A
3d80: 31 32 31 34 33 7d 20 54 68 65 20 63 61 6c 6c 69  12143} The calli
3d90: 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  ng function shou
3da0: 6c 64 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f  ld use [sqlite3_
3db0: 66 72 65 65 28 29 5d 20 74 6f 20 66 72 65 65 0a  free()] to free.
3dc0: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
3dd0: 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a 65 72 72  memory that *err
3de0: 6d 73 67 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  msg is left poin
3df0: 74 69 6e 67 20 61 74 20 6f 6e 63 65 20 74 68 65  ting at once the
3e00: 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20   error.**       
3e10: 20 20 20 6d 65 73 73 61 67 65 20 69 73 20 6e 6f     message is no
3e20: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
3e30: 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 35 7d 20 54  **.** {A12145} T
3e40: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3e50: 20 74 65 78 74 20 69 6e 20 74 68 65 20 32 6e 64   text in the 2nd
3e60: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
3e70: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a  qlite3_exec()].*
3e80: 2a 20 20 20 20 20 20 20 20 20 20 6d 75 73 74 20  *          must 
3e90: 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
3ea0: 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
3eb0: 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e 69  exec()] is runni
3ec0: 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ng..*/.int sqlit
3ed0: 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74  e3_exec(.  sqlit
3ee0: 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  e3*,            
3ef0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3f00: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
3f10: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
3f20: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst char *sql, 
3f30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3f40: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
3f50: 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
3f60: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c   */.  int (*call
3f70: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  back)(void*,int,
3f80: 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20  char**,char**), 
3f90: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e   /* Callback fun
3fa0: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
3fb0: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
3fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fd0: 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67        /* 1st arg
3fe0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63  ument to callbac
3ff0: 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72  k */.  char **er
4000: 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20  rmsg            
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
4030: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
4040: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
4050: 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20  F: Result Codes 
4060: 7b 48 31 30 32 31 30 7d 0a 2a 2a 20 4b 45 59 57  {H10210}.** KEYW
4070: 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20  ORDS: SQLITE_OK 
4080: 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72  {error code} {er
4090: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
40a0: 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20  YWORDS: {result 
40b0: 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f  code} {result co
40c0: 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  des}.**.** Many 
40d0: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
40e0: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
40f0: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
4100: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
4110: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
4120: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20  er to indicates 
4130: 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75  success or failu
4140: 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72  re..**.** New er
4150: 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65  ror codes may be
4160: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
4170: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4180: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ite..**.** See a
4190: 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  lso: [SQLITE_IOE
41a0: 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64  RR_READ | extend
41b0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
41c0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
41d0: 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20  TE_OK           
41e0: 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75  0   /* Successfu
41f0: 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62  l result */./* b
4200: 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f  eginning-of-erro
4210: 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69  r-codes */.#defi
4220: 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  ne SQLITE_ERROR 
4230: 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51         1   /* SQ
4240: 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69  L error or missi
4250: 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ng database */.#
4260: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4270: 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f  TERNAL     2   /
4280: 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63  * Internal logic
4290: 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65   error in SQLite
42a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
42b0: 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20  TE_PERM         
42c0: 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65  3   /* Access pe
42d0: 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20  rmission denied 
42e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
42f0: 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 34  E_ABORT        4
4300: 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72     /* Callback r
4310: 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 64  outine requested
4320: 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65   an abort */.#de
4330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
4340: 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20           5   /* 
4350: 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  The database fil
4360: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
4370: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
4380: 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 2f  CKED       6   /
4390: 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65  * A table in the
43a0: 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63   database is loc
43b0: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
43c0: 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20  QLITE_NOMEM     
43d0: 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c     7   /* A mall
43e0: 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23  oc() failed */.#
43f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
4400: 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f  ADONLY     8   /
4410: 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69  * Attempt to wri
4420: 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61  te a readonly da
4430: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
4440: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55  e SQLITE_INTERRU
4450: 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65  PT    9   /* Ope
4460: 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65  ration terminate
4470: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74  d by sqlite3_int
4480: 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69  errupt()*/.#defi
4490: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  ne SQLITE_IOERR 
44a0: 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f        10   /* So
44b0: 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20  me kind of disk 
44c0: 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72  I/O error occurr
44d0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
44e0: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20  LITE_CORRUPT    
44f0: 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74   11   /* The dat
4500: 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65  abase disk image
4510: 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f   is malformed */
4520: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4530: 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20  NOTFOUND    12  
4540: 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61   /* NOT USED. Ta
4550: 62 6c 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f  ble or record no
4560: 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69  t found */.#defi
4570: 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20  ne SQLITE_FULL  
4580: 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e        13   /* In
4590: 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62  sertion failed b
45a0: 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20  ecause database 
45b0: 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69  is full */.#defi
45c0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
45d0: 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e  EN    14   /* Un
45e0: 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  able to open the
45f0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
4600: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4610: 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20  _PROTOCOL    15 
4620: 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44    /* NOT USED. D
4630: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
4640: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
4650: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4660: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4670: 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d  * Database is em
4680: 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pty */.#define S
4690: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
46a0: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
46b0: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
46c0: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
46d0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
46e0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
46f0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
4700: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
4710: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4720: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4730: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4740: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4750: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4760: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4770: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4780: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4790: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
47a0: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
47b0: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
47c0: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
47d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47e0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
47f0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4800: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4810: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4830: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4840: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4850: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4860: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4870: 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69      24   /* Auxi
4880: 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66  liary database f
4890: 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23  ormat error */.#
48a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41  define SQLITE_RA
48b0: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f  NGE       25   /
48c0: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
48d0: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20  to sqlite3_bind 
48e0: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a  out of range */.
48f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4900: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20  OTADB      26   
4910: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74  /* File opened t
4920: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74  hat is not a dat
4930: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
4940: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57  efine SQLITE_ROW
4950: 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a           100  /*
4960: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4970: 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20  has another row 
4980: 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ready */.#define
4990: 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20   SQLITE_DONE    
49a0: 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69      101  /* sqli
49b0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66  te3_step() has f
49c0: 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
49d0: 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65  g */./* end-of-e
49e0: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f  rror-codes */../
49f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
4a00: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
4a10: 6f 64 65 73 20 7b 48 31 30 32 32 30 7d 0a 2a 2a  odes {H10220}.**
4a20: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4a30: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d  nded error code}
4a40: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
4a50: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f   codes}.** KEYWO
4a60: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
4a70: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74  esult code} {ext
4a80: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4a90: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  es}.**.** In its
4aa0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
4ab0: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4ac0: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4ad0: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74  rn one of 26 int
4ae0: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
4af0: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
4b00: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
4b10: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
4b20: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a  wn that many of.
4b30: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  ** these result 
4b40: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
4b50: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  arse-grained.  T
4b60: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
4b70: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
4b80: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
4b90: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
4ba0: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
4bb0: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
4bc0: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
4bd0: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
4be0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
4bf0: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
4c00: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
4c10: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
4c20: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
4c30: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
4c40: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4c50: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
4c60: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
4c70: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
4c80: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
4c90: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4ca0: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4cb0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4cc0: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4cd0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4ce0: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
4cf0: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a  des()] API..**.*
4d00: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76  * Some of the av
4d10: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64  ailable extended
4d20: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4d30: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a  e listed here..*
4d40: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74  * One may expect
4d50: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
4d60: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4d70: 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70  odes will be exp
4d80: 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65  and.** over time
4d90: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
4da0: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72   uses extended r
4db0: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75  esult codes shou
4dc0: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20  ld expect.** to 
4dd0: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63  see new result c
4de0: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72  odes in future r
4df0: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
4e00: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  e..**.** The SQL
4e10: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f  ITE_OK result co
4e20: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65  de will never be
4e30: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77   extended.  It w
4e40: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  ill always.** be
4e50: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a   exactly zero..*
4e60: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
4e70: 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 33 7d 20  .**.** {H10223} 
4e80: 54 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d  The symbolic nam
4e90: 65 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65  e for an extende
4ea0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 73 68  d result code sh
4eb0: 61 6c 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  all contains.** 
4ec0: 20 20 20 20 20 20 20 20 20 61 20 72 65 6c 61 74           a relat
4ed0: 65 64 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c  ed primary resul
4ee0: 74 20 63 6f 64 65 20 61 73 20 61 20 70 72 65 66  t code as a pref
4ef0: 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32  ix..**.** {H1022
4f00: 34 7d 20 50 72 69 6d 61 72 79 20 72 65 73 75 6c  4} Primary resul
4f10: 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61  t code names sha
4f20: 6c 6c 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e  ll contain a sin
4f30: 67 6c 65 20 22 5f 22 20 63 68 61 72 61 63 74 65  gle "_" characte
4f40: 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 35  r..**.** {H10225
4f50: 7d 20 45 78 74 65 6e 64 65 64 20 72 65 73 75 6c  } Extended resul
4f60: 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61  t code names sha
4f70: 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f  ll contain two o
4f80: 72 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61  r more "_" chara
4f90: 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  cters..**.** {H1
4fa0: 30 32 32 36 7d 20 54 68 65 20 6e 75 6d 65 72 69  0226} The numeri
4fb0: 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 78  c value of an ex
4fc0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4fd0: 64 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e  de shall contain
4fe0: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
4ff0: 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f   numeric value o
5000: 66 20 69 74 73 20 63 6f 72 72 65 73 70 6f 6e 64  f its correspond
5010: 69 6e 67 20 70 72 69 6d 61 72 79 20 72 65 73 75  ing primary resu
5020: 6c 74 20 63 6f 64 65 20 69 6e 0a 2a 2a 20 20 20  lt code in.**   
5030: 20 20 20 20 20 20 20 69 74 73 20 6c 65 61 73 74         its least
5040: 20 73 69 67 6e 69 66 69 63 61 6e 74 20 38 20 62   significant 8 b
5050: 69 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  its..*/.#define 
5060: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
5070: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  D              (
5080: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5090: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
50a0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
50b0: 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53  T_READ        (S
50c0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
50d0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
50e0: 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45  LITE_IOERR_WRITE
50f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5100: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c  LITE_IOERR | (3<
5110: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5120: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20  ITE_IOERR_FSYNC 
5130: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5140: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c  ITE_IOERR | (4<<
5150: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5160: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59  TE_IOERR_DIR_FSY
5170: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  NC         (SQLI
5180: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38  TE_IOERR | (5<<8
5190: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
51a0: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45  E_IOERR_TRUNCATE
51b0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
51c0: 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29  E_IOERR | (6<<8)
51d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51e0: 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20  _IOERR_FSTAT    
51f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5200: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29  _IOERR | (7<<8))
5210: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5220: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20  IOERR_UNLOCK    
5230: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5240: 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a  IOERR | (8<<8)).
5250: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5260: 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20  OERR_RDLOCK     
5270: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5280: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23  OERR | (9<<8)).#
5290: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52a0: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ERR_DELETE      
52b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
52c0: 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23  ERR | (10<<8)).#
52d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52e0: 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20  ERR_BLOCKED     
52f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5300: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23  ERR | (11<<8)).#
5310: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5320: 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ERR_NOMEM       
5330: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5340: 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23  ERR | (12<<8)).#
5350: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5360: 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20  ERR_ACCESS      
5370: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5380: 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23  ERR | (13<<8)).#
5390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
53a0: 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45  ERR_CHECKRESERVE
53b0: 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f  DLOCK (SQLITE_IO
53c0: 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 0a  ERR | (14<<8))..
53d0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
53e0: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f  Flags For File O
53f0: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b  pen Operations {
5400: 48 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e  H10230} <H11120>
5410: 20 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H12700>.**.** 
5420: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73  These bit values
5430: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
5440: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20  r use in the.** 
5450: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
5460: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
5470: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
5480: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65  ce and.** in the
5490: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
54a0: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
54b0: 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  od of the.** [sq
54c0: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
54d0: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
54e0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
54f0: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
5500: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
5510: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
5520: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
5530: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
5540: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
5550: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5560: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51  00004.#define SQ
5570: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
5580: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
5590: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
55a0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
55b0: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
55c0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
55d0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
55e0: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
55f0: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
5600: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
5610: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
5620: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
5630: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
5640: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
5650: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00400.#define SQ
5660: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
5670: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
5680: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00800.#define SQ
5690: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
56a0: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
56b0: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
56c0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
56d0: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
56e0: 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  02000.#define SQ
56f0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
5700: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
5710: 30 34 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  04000.#define SQ
5720: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
5730: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  X          0x000
5740: 30 38 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  08000../*.** CAP
5750: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
5760: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 48  aracteristics {H
5770: 31 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a  10240} <H11120>.
5780: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
5790: 65 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65  eCapabilities me
57a0: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
57b0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
57c0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
57d0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
57e0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
57f0: 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20  of the these.** 
5800: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
5810: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
5820: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
5830: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
5840: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
5850: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
5860: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
5870: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
5880: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
5890: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
58a0: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
58b0: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
58c0: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
58d0: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
58e0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
58f0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
5900: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
5910: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
5920: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
5930: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
5940: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
5950: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
5960: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
5970: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
5980: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
5990: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
59a0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
59b0: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
59c0: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
59d0: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
59e0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
59f0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
5a00: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
5a10: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
5a20: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
5a30: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
5a40: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
5a50: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
5a60: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
5a70: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
5a80: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
5a90: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
5aa0: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
5ab0: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
5ac0: 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  e()..*/.#define 
5ad0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5ae0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30  MIC          0x0
5af0: 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20  0000001.#define 
5b00: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b10: 4d 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30  MIC512       0x0
5b20: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
5b30: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b40: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30  MIC1K        0x0
5b50: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
5b60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b70: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30  MIC2K        0x0
5b80: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
5b90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5ba0: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30  MIC4K        0x0
5bb0: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
5bc0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5bd0: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30  MIC8K        0x0
5be0: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20  0000020.#define 
5bf0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5c00: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30  MIC16K       0x0
5c10: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
5c20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5c30: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30  MIC32K       0x0
5c40: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
5c50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5c60: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30  MIC64K       0x0
5c70: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20  0000100.#define 
5c80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
5c90: 45 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30  E_APPEND     0x0
5ca0: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
5cb0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
5cc0: 55 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30  UENTIAL      0x0
5cd0: 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0000400../*.** C
5ce0: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
5cf0: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31  cking Levels {H1
5d00: 30 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a  0250} <H11120>.*
5d10: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
5d20: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
5d30: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
5d40: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
5d50: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
5d60: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
5d70: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
5d80: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
5d90: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
5da0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
5db0: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
5dc0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
5dd0: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
5de0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
5df0: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
5e00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5e10: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
5e20: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
5e30: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
5e40: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
5e50: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
5e60: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
5e70: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
5e80: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
5e90: 20 46 6c 61 67 73 20 7b 48 31 30 32 36 30 7d 20   Flags {H10260} 
5ea0: 3c 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 57  <H11120>.**.** W
5eb0: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  hen SQLite invok
5ec0: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d  es the xSync() m
5ed0: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b  ethod of an.** [
5ee0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5ef0: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73  ds] object it us
5f00: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  es a combination
5f10: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74   of.** these int
5f20: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
5f30: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
5f40: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
5f50: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
5f60: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
5f70: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
5f80: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
5f90: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
5fa0: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
5fb0: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
5fc0: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
5fd0: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
5fe0: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 54  ot be flushed. T
5ff0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
6000: 4f 52 4d 41 4c 20 66 6c 61 67 20 6d 65 61 6e 73  ORMAL flag means
6010: 0a 2a 2a 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61  .** to use norma
6020: 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74  l fsync() semant
6030: 69 63 73 2e 20 54 68 65 20 53 51 4c 49 54 45 5f  ics. The SQLITE_
6040: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d  SYNC_FULL flag m
6050: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
6060: 61 63 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 75  ac OS-X style fu
6070: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
6080: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64  f fsync()..*/.#d
6090: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
60a0: 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20  C_NORMAL        
60b0: 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0x00002.#define 
60c0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
60d0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
60e0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
60f0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20  _SYNC_DATAONLY  
6100: 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a      0x00010../*.
6110: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
6120: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46  Interface Open F
6130: 69 6c 65 20 48 61 6e 64 6c 65 20 7b 48 31 31 31  ile Handle {H111
6140: 31 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a  10} <S20110>.**.
6150: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
6160: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
6170: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
6180: 69 6c 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a  ile in the OS.**
6190: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
61a0: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
61b0: 20 69 6e 74 65 72 66 61 63 65 20 69 6d 70 6c 65   interface imple
61c0: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
61d0: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
61e0: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
61f0: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
6200: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
6210: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
6220: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
6230: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
6240: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
6250: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6260: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
6270: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
6280: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
6290: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
62a0: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
62b0: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
62c0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
62d0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
62e0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
62f0: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
6300: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
6310: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
6320: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
6330: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
6340: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
6350: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
6360: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
6370: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 20   Methods Object 
6380: 7b 48 31 31 31 32 30 7d 20 3c 53 32 30 31 31 30  {H11120} <S20110
6390: 3e 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69  >.**.** Every fi
63a0: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65  le opened by the
63b0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
63c0: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75  Open method popu
63d0: 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c  lates an.** [sql
63e0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
63f0: 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d  t (or, more comm
6400: 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73  only, a subclass
6410: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
6420: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
6430: 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
6440: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
6450: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a  of this object..
6460: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64  ** This object d
6470: 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f  efines the metho
6480: 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f  ds used to perfo
6490: 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61  rm various opera
64a0: 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74  tions.** against
64b0: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72   the open file r
64c0: 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68  epresented by th
64d0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
64e0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54   object..**.** T
64f0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
6500: 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62  t to xSync may b
6510: 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  e one of [SQLITE
6520: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72  _SYNC_NORMAL] or
6530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  .** [SQLITE_SYNC
6540: 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72  _FULL].  The fir
6550: 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65  st choice is the
6560: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e   normal fsync().
6570: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63  .** The second c
6580: 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f  hoice is a Mac O
6590: 53 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S-X style fullsy
65a0: 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  nc.  The [SQLITE
65b0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a  _SYNC_DATAONLY].
65c0: 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f  ** flag may be O
65d0: 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61  Red in to indica
65e0: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
65f0: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
6600: 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73  e.** and not its
6610: 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20   inode needs to 
6620: 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a  be synced..**.**
6630: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   The integer val
6640: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61  ues to xLock() a
6650: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65  nd xUnlock() are
6660: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a   one of.** <ul>.
6670: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6680: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c  LOCK_NONE],.** <
6690: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
66a0: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  _SHARED],.** <li
66b0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  > [SQLITE_LOCK_R
66c0: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  ESERVED],.** <li
66d0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  > [SQLITE_LOCK_P
66e0: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c  ENDING], or.** <
66f0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6700: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20  _EXCLUSIVE]..** 
6710: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29  </ul>.** xLock()
6720: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c   increases the l
6730: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64  ock. xUnlock() d
6740: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ecreases the loc
6750: 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b  k..** The xCheck
6760: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d  ReservedLock() m
6770: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65  ethod checks whe
6780: 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73  ther any databas
6790: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a  e connection,.**
67a0: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20   either in this 
67b0: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f  process or in so
67c0: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  me other process
67d0: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52  , is holding a R
67e0: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44  ESERVED,.** PEND
67f0: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56  ING, or EXCLUSIV
6800: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69  E lock on the fi
6810: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  le.  It returns 
6820: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20  true.** if such 
6830: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e  a lock exists an
6840: 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73  d false otherwis
6850: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69  e..**.** The xFi
6860: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68  leControl() meth
6870: 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  od is a generic 
6880: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
6890: 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20  llows custom.** 
68a0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
68b0: 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20  ons to directly 
68c0: 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20  control an open 
68d0: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  file using the.*
68e0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
68f0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
6900: 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e  face.  The secon
6910: 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20  d "op" argument 
6920: 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  is an.** integer
6930: 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68   opcode.  The th
6940: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
6950: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65  a generic pointe
6960: 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a  r intended to.**
6970: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75   point to a stru
6980: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63  cture that may c
6990: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73  ontain arguments
69a0: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69   or space in whi
69b0: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72  ch to.** write r
69c0: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50  eturn values.  P
69d0: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f  otential uses fo
69e0: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  r xFileControl()
69f0: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e   might be.** fun
6a00: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65  ctions to enable
6a10: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20   blocking locks 
6a20: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74  with timeouts, t
6a30: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  o change the.** 
6a40: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79  locking strategy
6a50: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f   (for example to
6a60: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f   use dot-file lo
6a70: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65  cks), to inquire
6a80: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74  .** about the st
6a90: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20  atus of a lock, 
6aa0: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c  or to break stal
6ab0: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51  e locks.  The SQ
6ac0: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73  Lite.** core res
6ad0: 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65  erves all opcode
6ae0: 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  s less than 100 
6af0: 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e  for its own use.
6b00: 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43  .** A [SQLITE_FC
6b10: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20  NTL_LOCKSTATE | 
6b20: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
6b30: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
6b40: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
6b50: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
6b60: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
6b70: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
6b80: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
6b90: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
6ba0: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
6bb0: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
6bc0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
6bd0: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
6be0: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
6bf0: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
6c00: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
6c10: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
6c20: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
6c30: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
6c40: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
6c50: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
6c60: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
6c70: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
6c80: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
6c90: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
6ca0: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
6cb0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
6cc0: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
6cd0: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
6ce0: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
6cf0: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
6d00: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
6d10: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6d20: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
6d30: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
6d40: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
6d50: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6d60: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
6d70: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6d80: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
6d90: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6da0: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
6db0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6dc0: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
6dd0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6de0: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
6df0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e00: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
6e10: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6e20: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
6e30: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6e40: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
6e50: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6e60: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
6e70: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
6e80: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6e90: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
6ea0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
6eb0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
6ec0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
6ed0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6ee0: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
6ef0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
6f00: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
6f10: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
6f20: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
6f30: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
6f40: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
6f50: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
6f60: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
6f70: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
6f80: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6f90: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
6fa0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
6fb0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
6fc0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
6fd0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
6fe0: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
6ff0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
7000: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
7010: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
7020: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
7030: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
7040: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
7050: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
7060: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
7070: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
7080: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
7090: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
70a0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
70b0: 69 74 65 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65  ite()..*/.typede
70c0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
70d0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  _io_methods sqli
70e0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a  te3_io_methods;.
70f0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
7100: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  o_methods {.  in
7110: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
7120: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
7130: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
7140: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74  t (*xRead)(sqlit
7150: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c  e3_file*, void*,
7160: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
7170: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
7180: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29  .  int (*xWrite)
7190: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
71a0: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
71b0: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
71c0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
71d0: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28  nt (*xTruncate)(
71e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
71f0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a  qlite3_int64 siz
7200: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  e);.  int (*xSyn
7210: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  c)(sqlite3_file*
7220: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
7230: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29  int (*xFileSize)
7240: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7250: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
7260: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Size);.  int (*x
7270: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
7280: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
7290: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69   (*xUnlock)(sqli
72a0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
72b0: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52  .  int (*xCheckR
72c0: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c  eservedLock)(sql
72d0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
72e0: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
72f0: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
7300: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7310: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
7320: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
7330: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
7340: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
7350: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
7360: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
7370: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41  3_file*);.  /* A
7380: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64  dditional method
7390: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
73a0: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
73b0: 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
73c0: 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72  API3REF: Standar
73d0: 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f  d File Control O
73e0: 70 63 6f 64 65 73 20 7b 48 31 31 33 31 30 7d 20  pcodes {H11310} 
73f0: 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30800>.**.** T
7400: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
7410: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
7420: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
7430: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
7440: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
7450: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7460: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
7470: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
7480: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
7490: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
74a0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
74b0: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
74c0: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
74d0: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
74e0: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
74f0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
7500: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
7510: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
7520: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
7530: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
7540: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
7550: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
7560: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
7570: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
7580: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
7590: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
75a0: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
75b0: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
75c0: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
75d0: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
75e0: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
75f0: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
7600: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
7610: 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20   and only needs 
7620: 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20  to be supported 
7630: 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54  when SQLITE_TEST
7640: 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  .** is defined..
7650: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7660: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
7670: 45 20 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a  E        1../*.*
7680: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
7690: 78 20 48 61 6e 64 6c 65 20 7b 48 31 37 31 31 30  x Handle {H17110
76a0: 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 0a 2a 2a  } <S20130>.**.**
76b0: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
76c0: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
76d0: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
76e0: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
76f0: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
7700: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
7710: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
7720: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
7730: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
7740: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
7750: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
7760: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
7770: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
7780: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
7790: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
77a0: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
77b0: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
77c0: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
77d0: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
77e0: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
77f0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
7800: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
7810: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
7820: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
7830: 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 34 30 7d   Object {H11140}
7840: 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20100>.**.** 
7850: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
7860: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
7870: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
7880: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
7890: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74  een.** the SQLit
78a0: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75  e core and the u
78b0: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74  nderlying operat
78c0: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ing system.  The
78d0: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65   "vfs".** in the
78e0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a   name of the obj
78f0: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22  ect stands for "
7900: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
7910: 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tem"..**.** The 
7920: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
7930: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
7940: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
7950: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
7960: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
7970: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
7980: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
7990: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
79a0: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
79b0: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
79c0: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
79d0: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
79e0: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
79f0: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
7a00: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
7a10: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
7a20: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
7a30: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
7a40: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
7a50: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
7a60: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
7a70: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
7a80: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
7a90: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
7aa0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
7ab0: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
7ac0: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
7ad0: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
7ae0: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
7af0: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
7b00: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
7b10: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
7b20: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
7b30: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
7b40: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
7b50: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
7b60: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
7b70: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
7b80: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
7b90: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
7ba0: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
7bb0: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
7bc0: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
7bd0: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
7be0: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
7bf0: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
7c00: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
7c10: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
7c20: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
7c30: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
7c40: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
7c50: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
7c60: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
7c70: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
7c80: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
7c90: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
7ca0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
7cb0: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
7cc0: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
7cd0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
7ce0: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
7cf0: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
7d00: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
7d10: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
7d20: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
7d30: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
7d40: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
7d50: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
7d60: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
7d70: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
7d80: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
7d90: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
7da0: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
7db0: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
7dc0: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
7dd0: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
7de0: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
7df0: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
7e00: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
7e10: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
7e20: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
7e30: 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 31  s..**.** {H11141
7e40: 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67 75  } SQLite will gu
7e50: 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 65  arantee that the
7e60: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
7e70: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a  eter to xOpen.**
7e80: 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c   is either a NUL
7e90: 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72  L pointer or str
7ea0: 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ing obtained.** 
7eb0: 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61  from xFullPathna
7ec0: 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66 75  me().  SQLite fu
7ed0: 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73  rther guarantees
7ee0: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72   that.** the str
7ef0: 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ing will be vali
7f00: 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20  d and unchanged 
7f10: 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69  until xClose() i
7f20: 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 7b 45 4e  s.** called. {EN
7f30: 44 7d 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  D}  Because of t
7f40: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
7f50: 65 6e 73 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ense,.** the [sq
7f60: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
7f70: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
7f80: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
7f90: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
7fa0: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
7fb0: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
7fc0: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
7fd0: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
7fe0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
7ff0: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
8000: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
8010: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 69  pen.** must invi
8020: 74 65 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  te its own tempo
8030: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
8040: 65 20 66 69 6c 65 2e 20 20 57 68 65 6e 65 76 65  e file.  Wheneve
8050: 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e  r the .** xFilen
8060: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
8070: 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c   NULL it will al
8080: 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74  so be the case t
8090: 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73  hat the.** flags
80a0: 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20   parameter will 
80b0: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
80c0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
80d0: 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31  SE]..**.** {H111
80e0: 34 32 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72  42} The flags ar
80f0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
8100: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
8110: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
8120: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
8130: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
8140: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
8150: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
8160: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
8170: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
8180: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
8190: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
81a0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
81b0: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
81c0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
81d0: 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49 66 20 78  ]. {END}.** If x
81e0: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
81f0: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
8200: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
8210: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
8220: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
8230: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
8240: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
8250: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
8260: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 33 7d  ..**.** {H11143}
8270: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73   SQLite will als
8280: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
8290: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
82a0: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
82b0: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
82c0: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
82d0: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
82e0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
82f0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
8300: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
8310: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
8320: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
8330: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
8340: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
8350: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
8360: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
8370: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8380: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
8390: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
83a0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
83b0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
83c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
83d0: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
83e0: 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  /ul> {END}.**.**
83f0: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
8400: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
8410: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
8420: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
8430: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
8440: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
8450: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
8460: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
8470: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
8480: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
8490: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
84a0: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
84b0: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
84c0: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
84d0: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
84e0: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
84f0: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
8500: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
8510: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
8520: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
8530: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
8540: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
8550: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
8560: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
8570: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
8580: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
8590: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
85a0: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
85b0: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
85c0: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
85d0: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
85e0: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
85f0: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
8600: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
8610: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
8620: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
8630: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
8640: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
8650: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
8660: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
8670: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
8680: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
8690: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
86a0: 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 35  l>.**.** {H11145
86b0: 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  } The [SQLITE_OP
86c0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
86d0: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
86e0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a   file should be.
86f0: 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ** deleted when 
8700: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b  it is closed.  {
8710: 48 31 31 31 34 36 7d 20 54 68 65 20 5b 53 51 4c  H11146} The [SQL
8720: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
8730: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20  NCLOSE].** will 
8740: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20  be set for TEMP 
8750: 20 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72   databases, jour
8760: 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62  nals and for sub
8770: 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20  journals..**.** 
8780: 7b 48 31 31 31 34 37 7d 20 54 68 65 20 5b 53 51  {H11147} The [SQ
8790: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
87a0: 49 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20  IVE] flag means 
87b0: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
87c0: 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72  be opened.** for
87d0: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
87e0: 73 2e 20 20 54 68 69 73 20 66 6c 61 67 20 69 73  s.  This flag is
87f0: 20 73 65 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c   set for all fil
8800: 65 73 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72  es except.** for
8810: 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
8820: 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b  se file..**.** {
8830: 48 31 31 31 34 38 7d 20 41 74 20 6c 65 61 73 74  H11148} At least
8840: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
8850: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
8860: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
8870: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
8880: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
8890: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
88a0: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
88b0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
88c0: 70 65 6e 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20  pen. {END}  The 
88d0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
88e0: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
88f0: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
8900: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
8910: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
8920: 69 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34  in..**.** {H1114
8930: 39 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  9} The flags arg
8940: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
8950: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
8960: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
8970: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
8980: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
8990: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
89a0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
89b0: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
89c0: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
89d0: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
89e0: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
89f0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
8a00: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
8a10: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
8a20: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
8a30: 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 66 69 6c  . {END}  The fil
8a40: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  e can be a.** di
8a50: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b  rectory..**.** {
8a60: 48 31 31 31 35 30 7d 20 53 51 4c 69 74 65 20 77  H11150} SQLite w
8a70: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
8a80: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
8a90: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
8aa0: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
8ab0: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
8ac0: 74 68 6e 61 6d 65 2e 20 7b 48 31 31 31 35 31 7d  thname. {H11151}
8ad0: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
8ae0: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
8af0: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
8b00: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
8b10: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
8b20: 65 74 68 6f 64 73 2e 20 7b 45 4e 44 7d 20 20 49  ethods. {END}  I
8b30: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
8b40: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61  fer.** is not la
8b50: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c  rge enough, [SQL
8b60: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68  ITE_CANTOPEN] sh
8b70: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
8b80: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a  . Since this is.
8b90: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  ** handled as a 
8ba0: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
8bb0: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65  QLite, vfs imple
8bc0: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
8bd0: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f  d endeavor.** to
8be0: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
8bf0: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e   setting mxPathn
8c00: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69  ame to a suffici
8c10: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75  ently large valu
8c20: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61  e..**.** The xRa
8c30: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
8c40: 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  ep(), and xCurre
8c50: 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61  ntTime() interfa
8c60: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73  ces.** are not s
8c70: 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f  trictly a part o
8c80: 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d  f the filesystem
8c90: 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a  , but they are.*
8ca0: 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  * included in th
8cb0: 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20  e VFS structure 
8cc0: 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73  for completeness
8cd0: 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  ..** The xRandom
8ce0: 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  ness() function 
8cf0: 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75  attempts to retu
8d00: 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a  rn nBytes bytes.
8d10: 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69  ** of good-quali
8d20: 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  ty randomness in
8d30: 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65  to zOut.  The re
8d40: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a  turn value is.**
8d50: 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62   the actual numb
8d60: 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72  er of bytes of r
8d70: 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
8d80: 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65  ed..** The xSlee
8d90: 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65  p() method cause
8da0: 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68  s the calling th
8db0: 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f  read to sleep fo
8dc0: 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68  r at.** least th
8dd0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72  e number of micr
8de0: 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20  oseconds given. 
8df0: 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   The xCurrentTim
8e00: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
8e10: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
8e20: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
8e30: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
8e40: 6e 64 20 74 69 6d 65 2e 0a 2a 2f 0a 74 79 70 65  nd time..*/.type
8e50: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
8e60: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76  e3_vfs sqlite3_v
8e70: 66 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  fs;.struct sqlit
8e80: 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69  e3_vfs {.  int i
8e90: 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20  Version;        
8ea0: 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65      /* Structure
8eb0: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
8ec0: 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c  */.  int szOsFil
8ed0: 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  e;            /*
8ee0: 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73   Size of subclas
8ef0: 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  sed sqlite3_file
8f00: 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68   */.  int mxPath
8f10: 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f  name;          /
8f20: 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70  * Maximum file p
8f30: 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a  athname length *
8f40: 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20  /.  sqlite3_vfs 
8f50: 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20  *pNext;      /* 
8f60: 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20  Next registered 
8f70: 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  VFS */.  const c
8f80: 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20  har *zName;     
8f90: 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69    /* Name of thi
8fa0: 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73  s virtual file s
8fb0: 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20  ystem */.  void 
8fc0: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
8fd0: 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74      /* Pointer t
8fe0: 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70  o application-sp
8ff0: 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20  ecific data */. 
9000: 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
9010: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
9020: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
9030: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20  qlite3_file*,.  
9040: 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
9050: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75   flags, int *pOu
9060: 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28  tFlags);.  int (
9070: 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65  *xDelete)(sqlite
9080: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
9090: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73  ar *zName, int s
90a0: 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28  yncDir);.  int (
90b0: 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65  *xAccess)(sqlite
90c0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
90d0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66  ar *zName, int f
90e0: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f  lags, int *pResO
90f0: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75  ut);.  int (*xFu
9100: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69  llPathname)(sqli
9110: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
9120: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
9130: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
9140: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  t);.  void *(*xD
9150: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  lOpen)(sqlite3_v
9160: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
9170: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76  *zFilename);.  v
9180: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28  oid (*xDlError)(
9190: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
91a0: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
91b0: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20  ErrMsg);.  void 
91c0: 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74  *(*xDlSym)(sqlit
91d0: 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63  e3_vfs*,void*, c
91e0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62  onst char *zSymb
91f0: 6f 6c 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  ol);.  void (*xD
9200: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
9210: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
9220: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
9230: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
9240: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
9250: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
9260: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
9270: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
9280: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
9290: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
92a0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
92b0: 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  uble*);.  int (*
92c0: 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73  xGetLastError)(s
92d0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
92e0: 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 20  , char *);.  /* 
92f0: 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62  New fields may b
9300: 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69  e appended in fi
9310: 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20  gure versions.  
9320: 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a  The iVersion.  *
9330: 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63  * value will inc
9340: 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20  rement whenever 
9350: 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f  this happens. */
9360: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
9370: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
9380: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
9390: 65 74 68 6f 64 20 7b 48 31 31 31 39 30 7d 20 3c  ethod {H11190} <
93a0: 48 31 31 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48  H11140>.**.** {H
93b0: 31 31 31 39 31 7d 20 54 68 65 73 65 20 69 6e 74  11191} These int
93c0: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
93d0: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
93e0: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
93f0: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
9400: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
9410: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
9420: 62 6a 65 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68  bject. {END}  Th
9430: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  ey determine.** 
9440: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72  what kind of per
9450: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63  missions the xAc
9460: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c  cess method is l
9470: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 7b  ooking for..** {
9480: 48 31 31 31 39 32 7d 20 57 69 74 68 20 53 51 4c  H11192} With SQL
9490: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
94a0: 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
94b0: 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
94c0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
94d0: 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a  he file exists..
94e0: 2a 2a 20 7b 48 31 31 31 39 33 7d 20 57 69 74 68  ** {H11193} With
94f0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
9500: 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41  EADWRITE, the xA
9510: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
9520: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
9530: 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74 68 20  he file is both 
9540: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
9550: 74 61 62 6c 65 2e 0a 2a 2a 20 7b 48 31 31 31 39  table..** {H1119
9560: 34 7d 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  4} With SQLITE_A
9570: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
9580: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
9590: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
95a0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
95b0: 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  dable..*/.#defin
95c0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
95d0: 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66  EXISTS    0.#def
95e0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
95f0: 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23 64  S_READWRITE 1.#d
9600: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
9610: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a  ESS_READ      2.
9620: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
9630: 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20   Initialize The 
9640: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b  SQLite Library {
9650: 48 31 30 31 33 30 7d 20 3c 53 32 30 30 30 30 3e  H10130} <S20000>
9660: 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30100>.**.** T
9670: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
9680: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
9690: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a  initializes the.
96a0: 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  ** SQLite librar
96b0: 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  y.  The sqlite3_
96c0: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
96d0: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
96e0: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
96f0: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
9700: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
9710: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a  nitialize()..**.
9720: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
9730: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9740: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
9750: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
9760: 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74  s.** the first t
9770: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
9780: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
9790: 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c  ked during the l
97a0: 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68  ifetime of.** th
97b0: 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  e process, or if
97c0: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
97d0: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
97e0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
97f0: 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  voked.** followi
9800: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ng a call to sql
9810: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
9820: 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74    Only an effect
9830: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
9840: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9850: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
9860: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
9870: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
9880: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
9890: 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e  -ops..**.** Amon
98a0: 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20  g other things, 
98b0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
98c0: 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f 6b  ze() shall invok
98d0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  e.** sqlite3_os_
98e0: 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72  init().  Similar
98f0: 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 68 75 74  ly, sqlite3_shut
9900: 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c 20  down().** shall 
9910: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f  invoke sqlite3_o
9920: 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  s_end()..**.** T
9930: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
9940: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
9950: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f  returns SQLITE_O
9960: 4b 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  K on success..**
9970: 20 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61   If for some rea
9980: 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
9990: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
99a0: 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
99b0: 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
99c0: 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
99d0: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
99e0: 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
99f0: 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
9a00: 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
9a10: 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
9a20: 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 53  de] other than S
9a30: 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20  QLITE_OK..**.** 
9a40: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
9a50: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
9a60: 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72   is called inter
9a70: 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74  nally by many ot
9a80: 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
9a90: 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74  terfaces so that
9aa0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
9ab0: 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74  usually does not
9ac0: 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f   need to.** invo
9ad0: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
9ae0: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
9af0: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
9b00: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
9b10: 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65  .** calls sqlite
9b20: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73  3_initialize() s
9b30: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
9b40: 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74  rary will be aut
9b50: 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e  omatically.** in
9b60: 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b  itialized when [
9b70: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
9b80: 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20  is called if it 
9b90: 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69  has not be initi
9ba0: 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64  alized.** alread
9bb0: 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66 20  y.  However, if 
9bc0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
9bd0: 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
9be0: 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
9bf0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
9c00: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
9c10: 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
9c20: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
9c30: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
9c40: 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
9c50: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
9c60: 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
9c70: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
9c80: 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
9c90: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
9ca0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
9cb0: 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
9cc0: 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
9cd0: 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
9ce0: 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
9cf0: 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
9d00: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9d10: 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
9d20: 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
9d30: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
9d40: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
9d50: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
9d60: 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
9d70: 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
9d80: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
9d90: 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
9da0: 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
9db0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
9dc0: 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4f 4d 49   with SQLITE_OMI
9dd0: 54 5f 41 55 54 4f 49 4e 49 54 20 6d 69 67 68 74  T_AUTOINIT might
9de0: 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
9df0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
9e00: 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
9e10: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
9e20: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
9e30: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
9e40: 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
9e50: 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
9e60: 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
9e70: 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
9e80: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
9e90: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
9ea0: 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
9eb0: 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
9ec0: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
9ed0: 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
9ee0: 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
9ef0: 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
9f00: 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
9f10: 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
9f20: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
9f30: 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
9f40: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
9f50: 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
9f60: 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
9f70: 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
9f80: 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
9f90: 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
9fa0: 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
9fb0: 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
9fc0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
9fd0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
9fe0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
9ff0: 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
a000: 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
a010: 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
a020: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
a030: 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
a040: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
a050: 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
a060: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
a070: 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
a080: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
a090: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
a0a0: 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
a0b0: 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
a0c0: 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
a0d0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a0e0: 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
a0f0: 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
a100: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
a110: 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
a120: 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
a130: 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
a140: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
a150: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
a160: 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
a170: 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
a180: 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
a190: 64 20 66 6f 72 20 75 6e 69 78 2c 20 77 69 6e 64  d for unix, wind
a1a0: 6f 77 73 2c 20 6f 72 20 6f 73 2f 32 2e 0a 2a 2a  ows, or os/2..**
a1b0: 20 57 68 65 6e 20 62 75 69 6c 74 20 66 6f 72 20   When built for 
a1c0: 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 20  other platforms 
a1d0: 28 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54  (using the SQLIT
a1e0: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 20 63 6f 6d  E_OS_OTHER=1 com
a1f0: 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
a200: 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
a210: 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
a220: 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
a230: 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
a240: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
a250: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
a260: 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
a270: 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
a280: 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
a290: 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
a2a0: 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
a2b0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
a2c0: 20 6d 75 73 74 20 72 65 74 75 72 6e 20 53 51 4c   must return SQL
a2d0: 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73  ITE_OK on succes
a2e0: 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72  s and some other
a2f0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70   [error code] up
a300: 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a  on.** failure..*
a310: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e  /.int sqlite3_in
a320: 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a  itialize(void);.
a330: 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  int sqlite3_shut
a340: 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20  down(void);.int 
a350: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
a360: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
a370: 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b  e3_os_end(void);
a380: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
a390: 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68  : Configuring Th
a3a0: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
a3b0: 20 7b 48 31 30 31 34 35 7d 20 3c 53 32 30 30 30   {H10145} <S2000
a3c0: 30 3e 3c 53 33 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  0><S30200>.**.**
a3d0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
a3e0: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
a3f0: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
a400: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
a410: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
a420: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
a430: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
a440: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
a450: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
a460: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
a470: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
a480: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
a490: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
a4a0: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
a4b0: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
a4c0: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
a4d0: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
a4e0: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
a4f0: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
a500: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
a510: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
a520: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ds..**.** The sq
a530: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
a540: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
a550: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
a560: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
a570: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
a580: 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
a590: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
a5a0: 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
a5b0: 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
a5c0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
a5d0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  () is running.  
a5e0: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c  Furthermore, sql
a5f0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a  ite3_config().**
a600: 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76   may only be inv
a610: 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69  oked prior to li
a620: 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61  brary initializa
a630: 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
a640: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a650: 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68  e()] or after sh
a660: 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74  utdown by [sqlit
a670: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
a680: 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
a690: 2c 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 63  , that sqlite3_c
a6a0: 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63  onfig() can be c
a6b0: 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66  alled as part of
a6c0: 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
a6d0: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70  tation of an app
a6e0: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
a6f0: 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69   [sqlite3_os_ini
a700: 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  t()]..**.** The 
a710: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
a720: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
a730: 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  () is an integer
a740: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
a750: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
a760: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
a770: 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
a780: 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
a790: 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
a7a0: 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
a7b0: 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
a7c0: 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
a7d0: 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
a7e0: 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  on the [SQLITE_C
a7f0: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
a800: 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  AD | configurati
a810: 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  on option].** in
a820: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
a830: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ent..**.** When 
a840: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
a850: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
a860: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
a870: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f  returns SQLITE_O
a880: 4b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 74  K..** If the opt
a890: 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f  ion is unknown o
a8a0: 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  r SQLite is unab
a8b0: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70  le to set the op
a8c0: 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69  tion.** then thi
a8d0: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
a8e0: 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  s a non-zero [er
a8f0: 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
a900: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
a910: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
a920: 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78  is considered ex
a930: 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 20 74 68  perimental in th
a940: 61 74 0a 2a 2a 20 6e 65 77 20 63 6f 6e 66 69 67  at.** new config
a950: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
a960: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
a970: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
a980: 61 6e 64 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20  and existing.** 
a990: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
a9a0: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 64 69 73  tions may be dis
a9b0: 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 6d 6f 64  continued or mod
a9c0: 69 66 69 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ified..*/.int sq
a9d0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
a9e0: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
a9f0: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
aa00: 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
aa10: 6e 65 73 20 7b 48 31 30 31 35 35 7d 20 3c 53 32  nes {H10155} <S2
aa20: 30 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  0120>.**.** An i
aa30: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
aa40: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
aa50: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
aa60: 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ween SQLite.** a
aa70: 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  nd low-level mem
aa80: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
aa90: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
aaa0: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73  his object is us
aab0: 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70  ed in only one p
aac0: 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69  lace in the SQLi
aad0: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
aae0: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   A pointer to an
aaf0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
ab00: 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20  s object is the 
ab10: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b  argument to.** [
ab20: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ab30: 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69  ] when the confi
ab40: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
ab50: 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  is.** [SQLITE_CO
ab60: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 42  NFIG_MALLOC].  B
ab70: 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e  y creating an in
ab80: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
ab90: 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73  bject.** and pas
aba0: 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
abb0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 64 75  te3_config()] du
abc0: 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ring configurati
abd0: 6f 6e 2c 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63  on, an.** applic
abe0: 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66  ation can specif
abf0: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
ac00: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
ac10: 6f 6e 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20  on subsystem.** 
ac20: 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
ac30: 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
ac40: 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
ac50: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  needs..**.** Not
ac60: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f  e that SQLite co
ac70: 6d 65 73 20 77 69 74 68 20 61 20 62 75 69 6c 74  mes with a built
ac80: 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
ac90: 61 74 6f 72 20 74 68 61 74 20 69 73 0a 2a 2a 20  ator that is.** 
aca0: 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61  perfectly adequa
acb0: 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77  te for the overw
acc0: 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79  helming majority
acd0: 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
ace0: 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69  .** and that thi
acf0: 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79  s object is only
ad00: 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e   useful to a tin
ad10: 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70  y minority of ap
ad20: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69  plications.** wi
ad30: 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d  th specialized m
ad40: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
ad50: 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20   requirements.  
ad60: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a  This object is.*
ad70: 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69  * also used duri
ad80: 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51  ng testing of SQ
ad90: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
ada0: 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
adb0: 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
adc0: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
add0: 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72   simulates memor
ade0: 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20  y out-of-memory 
adf0: 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a  conditions in.**
ae00: 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79   order to verify
ae10: 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63   that SQLite rec
ae20: 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79  overs gracefully
ae30: 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f   from such.** co
ae40: 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nditions..**.** 
ae50: 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 46 72  The xMalloc, xFr
ae60: 65 65 2c 20 61 6e 64 20 78 52 65 61 6c 6c 6f 63  ee, and xRealloc
ae70: 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f   methods must wo
ae80: 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d  rk like the.** m
ae90: 61 6c 6c 6f 63 28 29 2c 20 66 72 65 65 28 29 2c  alloc(), free(),
aea0: 20 61 6e 64 20 72 65 61 6c 6c 6f 63 28 29 20 66   and realloc() f
aeb0: 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
aec0: 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61  e standard libra
aed0: 72 79 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  ry..**.** xSize 
aee0: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
aef0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
af00: 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
af10: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
af20: 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
af30: 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
af40: 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
af50: 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
af60: 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
af70: 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
af80: 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
af90: 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
afa0: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
afb0: 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
afc0: 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
afd0: 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
afe0: 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
aff0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
b000: 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
b010: 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
b020: 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
b030: 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
b040: 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
b050: 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
b060: 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
b070: 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
b080: 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
b090: 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
b0a0: 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
b0b0: 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
b0c0: 20 32 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49   2..**.** The xI
b0d0: 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69  nit method initi
b0e0: 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72  alizes the memor
b0f0: 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46  y allocator.  (F
b100: 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
b110: 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65  t might allocate
b120: 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74   any require mut
b130: 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69  exes or initiali
b140: 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ze internal data
b150: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20  .** structures. 
b160: 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d   The xShutdown m
b170: 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
b180: 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79   (indirectly) by
b190: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
b1a0: 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f  tdown()] and sho
b1b0: 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61  uld deallocate a
b1c0: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71  ny resources acq
b1d0: 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69  uired.** by xIni
b1e0: 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61  t.  The pAppData
b1f0: 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64   pointer is used
b200: 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
b210: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e  ameter to.** xIn
b220: 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  it and xShutdown
b230: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
b240: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
b250: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
b260: 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
b270: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
b280: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
b290: 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
b2a0: 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
b2b0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
b2c0: 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
b2d0: 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
b2e0: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
b2f0: 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
b300: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
b310: 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
b320: 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
b330: 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
b340: 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
b350: 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
b360: 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
b370: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
b380: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
b390: 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
b3a0: 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
b3b0: 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
b3c0: 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
b3d0: 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
b3e0: 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
b3f0: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
b400: 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
b410: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
b420: 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
b430: 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
b440: 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
b450: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
b460: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
b470: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
b480: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
b490: 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
b4a0: 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
b4b0: 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
b4c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
b4d0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
b4e0: 6f 6e 73 20 7b 48 31 30 31 36 30 7d 20 3c 53 32  ons {H10160} <S2
b4f0: 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0000>.**.** Thes
b500: 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
b510: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
b520: 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
b530: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
b540: 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
b550: 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
b560: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
b570: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
b580: 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
b590: 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
b5a0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
b5b0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
b5c0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
b5d0: 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
b5e0: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
b5f0: 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
b600: 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
b610: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
b620: 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
b630: 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
b640: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  rom [sqlite3_con
b650: 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
b660: 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
b670: 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68  call worked.  Th
b680: 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
b690: 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
b6a0: 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
b6b0: 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
b6c0: 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
b6d0: 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
b6e0: 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
b6f0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
b700: 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
b710: 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
b720: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
b730: 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ETHREAD</dt>.** 
b740: 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
b750: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
b760: 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73  is option.  This
b770: 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73   option disables
b780: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
b790: 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
b7a0: 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
b7b0: 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
b7c0: 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
b7d0: 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 3c 2f 64  ingle thread.</d
b7e0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
b7f0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
b800: 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
b810: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
b820: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
b830: 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20  s option.  This 
b840: 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a  option disables.
b850: 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b  ** mutexing on [
b860: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
b870: 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
b880: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
b890: 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70  jects..** The ap
b8a0: 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73  plication is res
b8b0: 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72  ponsible for ser
b8c0: 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20  ializing access 
b8d0: 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  to.** [database 
b8e0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
b8f0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
b900: 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68  ments].  But oth
b910: 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  er mutexes.** ar
b920: 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61  e enabled so tha
b930: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  t SQLite will be
b940: 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20   safe to use in 
b950: 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
b960: 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2e  .** environment.
b970: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
b980: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
b990: 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
b9a0: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
b9b0: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
b9c0: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69  his option.  Thi
b9d0: 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73  s option enables
b9e0: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20  .** all mutexes 
b9f0: 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65  including the re
ba00: 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78  cursive.** mutex
ba10: 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  es on [database 
ba20: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
ba30: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
ba40: 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
ba50: 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77   In this mode (w
ba60: 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61  hich is the defa
ba70: 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ult when SQLite 
ba80: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
ba90: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
baa0: 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53  ADSAFE=1]) the S
bab0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
bac0: 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c  ll itself serial
bad0: 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ize access.** to
bae0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
baf0: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
bb00: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
bb10: 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a  ] so that the.**
bb20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
bb30: 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20  free to use the 
bb40: 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
bb50: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68  onnection] or th
bb60: 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61  e.** same [prepa
bb70: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
bb80: 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  n different thre
bb90: 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
bba0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 70 3e 54  time..**.** <p>T
bbb0: 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
bbc0: 6e 20 6f 70 74 69 6f 6e 20 6d 65 72 65 6c 79 20  n option merely 
bbd0: 73 65 74 73 20 74 68 65 20 64 65 66 61 75 6c 74  sets the default
bbe0: 20 6d 75 74 65 78 20 0a 2a 2a 20 62 65 68 61 76   mutex .** behav
bbf0: 69 6f 72 20 74 6f 20 73 65 72 69 61 6c 69 7a 65  ior to serialize
bc00: 20 61 63 63 65 73 73 20 74 6f 20 5b 64 61 74 61   access to [data
bc10: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
bc20: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 0a 2a  ].  Individual.*
bc30: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
bc40: 65 63 74 69 6f 6e 73 5d 20 63 61 6e 20 6f 76 65  ections] can ove
bc50: 72 72 69 64 65 20 74 68 69 73 20 73 65 74 74 69  rride this setti
bc60: 6e 67 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20  ng.** using the 
bc70: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
bc80: 55 54 45 58 5d 20 66 6c 61 67 20 74 6f 20 5b 73  UTEX] flag to [s
bc90: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
bca0: 5d 2e 3c 2f 70 3e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ].</p></dd>.**.*
bcb0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
bcc0: 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
bcd0: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
bce0: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
bcf0: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
bd00: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
bd10: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
bd20: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
bd30: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
bd40: 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
bd50: 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
bd60: 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
bd70: 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
bd80: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
bd90: 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
bda0: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68  n place of.** th
bdb0: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
bdc0: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69  ion routines bui
bdd0: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c  lt into SQLite.<
bde0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
bdf0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
be00: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
be10: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
be20: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
be30: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
be40: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
be50: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
be60: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
be70: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
be80: 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  re.  The [sqlite
be90: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
bea0: 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
beb0: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
bec0: 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
bed0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
bee0: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  on routines..** 
bef0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
bf00: 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
bf10: 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
bf20: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
bf30: 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
bf40: 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61  th a wrapper tha
bf50: 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65  t simulations me
bf60: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
bf70: 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72  failure or.** tr
bf80: 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67  acks memory usag
bf90: 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c  e, for example.<
bfa0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
bfb0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
bfc0: 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  STATUS</dt>.** <
bfd0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
bfe0: 61 6b 65 73 20 73 69 6e 67 6c 65 20 62 6f 6f 6c  akes single bool
bff0: 65 61 6e 20 61 72 67 75 6d 65 6e 74 20 77 68 69  ean argument whi
c000: 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ch enables or di
c010: 73 61 62 6c 65 73 0a 2a 2a 20 74 68 65 20 63 6f  sables.** the co
c020: 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f  llection of memo
c030: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
c040: 61 74 69 73 74 69 63 73 2e 20 20 57 68 65 6e 20  atistics.  When 
c050: 64 69 73 61 62 6c 65 64 2c 20 74 68 65 0a 2a 2a  disabled, the.**
c060: 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74   following SQLit
c070: 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63  e interfaces bec
c080: 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  ome non-operatio
c090: 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
c0a0: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
c0b0: 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
c0c0: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
c0d0: 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
c0e0: 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
c0f0: 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
c100: 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  heap_limit()].**
c110: 20 20 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f     <li> sqlite3_
c120: 6d 65 6d 6f 72 79 5f 73 74 61 74 75 73 28 29 0a  memory_status().
c130: 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f  **   </ul>.** </
c140: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
c150: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
c160: 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
c170: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
c180: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
c190: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
c1a0: 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
c1b0: 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20   for.** scratch 
c1c0: 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61  memory.  There a
c1d0: 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
c1e0: 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 74  ts:  A pointer t
c1f0: 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68  o the memory, th
c200: 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
c210: 68 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  h scratch buffer
c220: 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
c230: 75 6d 62 65 72 20 6f 66 20 62 75 66 66 65 72 73  umber of buffers
c240: 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a   (N).  The sz.**
c250: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
c260: 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  e a multiple of 
c270: 31 36 2e 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  16. The first.**
c280: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
c290: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c   point to an all
c2a0: 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65  ocation of at le
c2b0: 61 73 74 20 28 73 7a 2b 34 29 2a 4e 20 62 79 74  ast (sz+4)*N byt
c2c0: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
c2d0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
c2e0: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e   no more than on
c2f0: 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  e scratch buffer
c300: 20 61 74 20 6f 6e 63 65 20 70 65 72 20 74 68 72   at once per thr
c310: 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f  ead, so.** N sho
c320: 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 68  uld be set to th
c330: 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d  e expected maxim
c340: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72  um number of thr
c350: 65 61 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a 2a  eads.  The sz.**
c360: 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c   parameter shoul
c370: 64 20 62 65 20 36 20 74 69 6d 65 73 20 74 68 65  d be 6 times the
c380: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
c390: 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
c3a0: 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 61  ge size..** Scra
c3b0: 74 63 68 20 62 75 66 66 65 72 73 20 61 72 65 20  tch buffers are 
c3c0: 75 73 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  used as part of 
c3d0: 74 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63  the btree balanc
c3e0: 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49 66  e operation.  If
c3f0: 0a 2a 2a 20 54 68 65 20 62 74 72 65 65 20 62 61  .** The btree ba
c400: 6c 61 6e 63 65 72 20 6e 65 65 64 73 20 61 64 64  lancer needs add
c410: 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 62  itional memory b
c420: 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
c430: 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20 73 63 72  ovided by.** scr
c440: 61 74 63 68 20 62 75 66 66 65 72 73 20 6f 72 20  atch buffers or 
c450: 69 66 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75  if no scratch bu
c460: 66 66 65 72 20 73 70 61 63 65 20 69 73 20 73 70  ffer space is sp
c470: 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 53 51  ecified, then SQ
c480: 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f 20  Lite.** goes to 
c490: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
c4a0: 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  )] to obtain the
c4b0: 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65 64 73   memory it needs
c4c0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
c4d0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
c4e0: 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  AGECACHE</dt>.**
c4f0: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
c500: 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
c510: 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
c520: 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
c530: 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65  n use for.** the
c540: 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
c550: 61 63 68 65 2e 20 20 54 68 65 72 65 20 61 72 65  ache.  There are
c560: 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
c570: 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  : A pointer to t
c580: 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68  he.** memory, th
c590: 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70  e size of each p
c5a0: 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c  age buffer (sz),
c5b0: 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
c5c0: 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a  of pages (N)..**
c5d0: 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
c5e0: 20 6d 75 73 74 20 62 65 20 61 20 70 6f 77 65 72   must be a power
c5f0: 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
c600: 35 31 32 20 61 6e 64 20 33 32 37 36 38 2e 20 20  512 and 32768.  
c610: 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
c620: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
c630: 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74  nt to an allocat
c640: 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ion of at least 
c650: 28 73 7a 2b 34 29 2a 4e 20 62 79 74 65 73 20 6f  (sz+4)*N bytes o
c660: 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c  f memory..** SQL
c670: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
c680: 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
c690: 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72   by the first ar
c6a0: 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66  gument to satisf
c6b0: 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20  y its.** memory 
c6c0: 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69  needs for the fi
c6d0: 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74  rst N pages that
c6e0: 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68   it adds to cach
c6f0: 65 2e 20 20 49 66 20 61 64 64 69 74 69 6f 6e 61  e.  If additiona
c700: 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
c710: 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
c720: 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
c730: 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
c740: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a   option, then.**
c750: 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
c760: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
c770: 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74  )] for the addit
c780: 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70  ional storage sp
c790: 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ace.</dd>.**.** 
c7a0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
c7b0: 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
c7c0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  dd>This option s
c7d0: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
c7e0: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
c7f0: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
c800: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20   use.** for all 
c810: 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
c820: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
c830: 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68   needs beyond th
c840: 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  ose provided.** 
c850: 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
c860: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61  ONFIG_SCRATCH] a
c870: 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  nd [SQLITE_CONFI
c880: 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
c890: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
c8a0: 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f   arguments: A po
c8b0: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
c8c0: 6f 72 79 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ory, the number 
c8d0: 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
c8e0: 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
c8f0: 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
c900: 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
c910: 65 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 66 69  e.  If.** the fi
c920: 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
c930: 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
c940: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
c950: 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
c960: 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
c970: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
c980: 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
c990: 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
c9a0: 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
c9b0: 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
c9c0: 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
c9d0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
c9e0: 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68 65 0a  ALLOC].  If the.
c9f0: 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  ** memory pointe
ca00: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e  r is not NULL an
ca10: 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  d either [SQLITE
ca20: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
ca30: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45   or.** [SQLITE_E
ca40: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61  NABLE_MEMSYS5] a
ca50: 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e  re defined, then
ca60: 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
ca70: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
ca80: 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
ca90: 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
caa0: 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
cab0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
cac0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
cad0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
cae0: 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
caf0: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
cb00: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
cb10: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
cb20: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
cb30: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
cb40: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
cb50: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
cb60: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
cb70: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
cb80: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
cb90: 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
cba0: 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
cbb0: 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d  n place.** the m
cbc0: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
cbd0: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
cbe0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
cbf0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
cc00: 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  TMUTEX</dt>.** <
cc10: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
cc20: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
cc30: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
cc40: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
cc50: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
cc60: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
cc70: 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
cc80: 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
cc90: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
cca0: 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
ccb0: 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
ccc0: 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
ccd0: 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
cce0: 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20  utines..** This 
ccf0: 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
cd00: 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
cd10: 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
cd20: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
cd30: 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
cd40: 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
cd50: 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
cd60: 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
cd70: 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
cd80: 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
cd90: 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2f 0a 23  ample.</dd>.*/.#
cda0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
cdb0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
cdc0: 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
cdd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
cde0: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
cdf0: 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
ce00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ce10: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
ce20: 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
ce30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
ce40: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
ce50: 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
ce60: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
ce70: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
ce80: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
ce90: 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
cea0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
ceb0: 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
cec0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
ced0: 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
cee0: 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
cef0: 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
cf00: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
cf10: 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
cf20: 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
cf30: 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
cf40: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
cf50: 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
cf60: 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
cf70: 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
cf80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cf90: 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
cfa0: 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
cfb0: 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
cfc0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
cfd0: 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
cfe0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
cff0: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
d000: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
d010: 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
d020: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
d030: 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a 0a  x_methods* */...
d040: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d050: 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
d060: 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  e Extended Resul
d070: 74 20 43 6f 64 65 73 20 7b 48 31 32 32 30 30 7d  t Codes {H12200}
d080: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
d090: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
d0a0: 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69  lt_codes() routi
d0b0: 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
d0c0: 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65  sables the.** [e
d0d0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
d0e0: 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
d0f0: 20 53 51 4c 69 74 65 2e 20 54 68 65 20 65 78 74   SQLite. The ext
d100: 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20  ended result.** 
d110: 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c  codes are disabl
d120: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
d130: 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d  r historical com
d140: 70 61 74 69 62 69 6c 69 74 79 20 63 6f 6e 73 69  patibility consi
d150: 64 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  derations..**.**
d160: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
d170: 2a 2a 20 7b 48 31 32 32 30 31 7d 20 45 61 63 68  ** {H12201} Each
d180: 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63   new [database c
d190: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 68 61 6c 6c  onnection] shall
d1a0: 20 68 61 76 65 20 74 68 65 0a 2a 2a 20 20 20 20   have the.**    
d1b0: 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20        [extended 
d1c0: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
d1d0: 61 74 75 72 65 20 64 69 73 61 62 6c 65 64 20 62  ature disabled b
d1e0: 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
d1f0: 20 7b 48 31 32 32 30 32 7d 20 54 68 65 20 5b 73   {H12202} The [s
d200: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
d210: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 44 2c 46  result_codes(D,F
d220: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  )] interface sha
d230: 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20 20 20 20  ll enable.**    
d240: 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20        [extended 
d250: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 6f  result codes] fo
d260: 72 20 74 68 65 20 20 5b 64 61 74 61 62 61 73 65  r the  [database
d270: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
d280: 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 74 68  *          if th
d290: 65 20 46 20 70 61 72 61 6d 65 74 65 72 20 69 73  e F parameter is
d2a0: 20 74 72 75 65 2c 20 6f 72 20 64 69 73 61 62 6c   true, or disabl
d2b0: 65 20 74 68 65 6d 20 69 66 20 46 20 69 73 20 66  e them if F is f
d2c0: 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  alse..*/.int sql
d2d0: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
d2e0: 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
d2f0: 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
d300: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
d310: 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
d320: 77 69 64 20 7b 48 31 32 32 32 30 7d 20 3c 53 31  wid {H12220} <S1
d330: 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 45 61 63 68  0700>.**.** Each
d340: 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c   entry in an SQL
d350: 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  ite table has a 
d360: 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
d370: 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
d380: 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 22  key called the "
d390: 72 6f 77 69 64 22 2e 20 54 68 65 20 72 6f 77 69  rowid". The rowi
d3a0: 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
d3b0: 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75  lable.** as an u
d3c0: 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e  ndeclared column
d3d0: 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
d3e0: 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73  D, or _ROWID_ as
d3f0: 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a   long as those.*
d400: 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20  * names are not 
d410: 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70  also used by exp
d420: 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
d430: 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20   columns. If.** 
d440: 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  the table has a 
d450: 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 49  column of type I
d460: 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
d470: 45 59 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c  EY then that col
d480: 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65  umn.** is anothe
d490: 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20  r alias for the 
d4a0: 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  rowid..**.** Thi
d4b0: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
d4c0: 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74  s the rowid of t
d4d0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
d4e0: 2a 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53  * successful INS
d4f0: 45 52 54 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ERT into the dat
d500: 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b  abase from the [
d510: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d520: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
d530: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20  irst argument.  
d540: 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
d550: 20 49 4e 53 45 52 54 73 0a 2a 2a 20 68 61 76 65   INSERTs.** have
d560: 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f   ever occurred o
d570: 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20  n that database 
d580: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f  connection, zero
d590: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
d5a0: 0a 2a 2a 20 49 66 20 61 6e 20 49 4e 53 45 52 54  .** If an INSERT
d5b0: 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
d5c0: 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74   trigger, then t
d5d0: 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20  he rowid of the 
d5e0: 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20  inserted.** row 
d5f0: 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  is returned by t
d600: 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c  his routine as l
d610: 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
d620: 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  er is running..*
d630: 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74  * But once the t
d640: 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65  rigger terminate
d650: 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  s, the value ret
d660: 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f  urned by this ro
d670: 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73  utine.** reverts
d680: 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c   to the last val
d690: 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f  ue inserted befo
d6a0: 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 66  re the trigger f
d6b0: 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 49  ired..**.** An I
d6c0: 4e 53 45 52 54 20 74 68 61 74 20 66 61 69 6c 73  NSERT that fails
d6d0: 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
d6e0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
d6f0: 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
d700: 73 73 66 75 6c 20 49 4e 53 45 52 54 20 61 6e 64  ssful INSERT and
d710: 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
d720: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
d730: 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
d740: 6f 75 74 69 6e 65 2e 20 20 54 68 75 73 20 49 4e  outine.  Thus IN
d750: 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
d760: 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
d770: 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
d780: 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
d790: 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
d7a0: 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
d7b0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
d7c0: 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
d7d0: 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
d7e0: 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57  ertion fails.  W
d7f0: 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
d800: 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
d810: 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
d820: 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
d830: 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
d840: 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
d850: 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
d860: 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
d870: 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
d880: 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
d890: 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
d8a0: 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
d8b0: 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
d8c0: 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
d8d0: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
d8e0: 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
d8f0: 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70  .** For the purp
d900: 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
d910: 74 69 6e 65 2c 20 61 6e 20 49 4e 53 45 52 54 20  tine, an INSERT 
d920: 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  is considered to
d930: 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75  .** be successfu
d940: 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  l even if it is 
d950: 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c  subsequently rol
d960: 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
d970: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
d980: 2a 20 7b 48 31 32 32 32 31 7d 20 54 68 65 20 5b  * {H12221} The [
d990: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
d9a0: 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e  ert_rowid()] fun
d9b0: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
d9c0: 65 20 72 6f 77 69 64 0a 2a 2a 20 20 20 20 20 20  e rowid.**      
d9d0: 20 20 20 20 6f 66 20 74 68 65 20 6d 6f 73 74 20      of the most 
d9e0: 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75  recent successfu
d9f0: 6c 20 49 4e 53 45 52 54 20 70 65 72 66 6f 72 6d  l INSERT perform
da00: 65 64 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  ed on the same.*
da10: 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
da20: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
da30: 20 61 6e 64 20 77 69 74 68 69 6e 20 74 68 65 20   and within the 
da40: 73 61 6d 65 20 6f 72 20 68 69 67 68 65 72 20 6c  same or higher l
da50: 65 76 65 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  evel.**         
da60: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
da70: 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65  , or zero if the
da80: 72 65 20 68 61 76 65 20 62 65 65 6e 20 6e 6f 20  re have been no 
da90: 71 75 61 6c 69 66 79 69 6e 67 20 69 6e 73 65 72  qualifying inser
daa0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32  ts..**.** {H1222
dab0: 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
dac0: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
dad0: 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65  d()] function re
dae0: 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
daf0: 20 20 20 20 20 20 73 61 6d 65 20 76 61 6c 75 65        same value
db00: 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f   when called fro
db10: 6d 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  m the same trigg
db20: 65 72 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20  er context.**   
db30: 20 20 20 20 20 20 20 69 6d 6d 65 64 69 61 74 65         immediate
db40: 6c 79 20 62 65 66 6f 72 65 20 61 6e 64 20 61 66  ly before and af
db50: 74 65 72 20 61 20 52 4f 4c 4c 42 41 43 4b 2e 0a  ter a ROLLBACK..
db60: 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e  **.** ASSUMPTION
db70: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 33 32  S:.**.** {A12232
db80: 7d 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  } If a separate 
db90: 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20  thread performs 
dba0: 61 20 6e 65 77 20 49 4e 53 45 52 54 20 6f 6e 20  a new INSERT on 
dbb0: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20  the same.**     
dbc0: 20 20 20 20 20 64 61 74 61 62 61 73 65 20 63 6f       database co
dbd0: 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
dbe0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
dbf0: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
dc00: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e  .**          fun
dc10: 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
dc20: 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65   and thus change
dc30: 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
dc40: 74 20 72 6f 77 69 64 2c 0a 2a 2a 20 20 20 20 20  t rowid,.**     
dc50: 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 76 61       then the va
dc60: 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
dc70: 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
dc80: 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
dc90: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e 70  .**          unp
dca0: 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d  redictable and m
dcb0: 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65  ight not equal e
dcc0: 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72  ither the old or
dcd0: 20 74 68 65 20 6e 65 77 0a 2a 2a 20 20 20 20 20   the new.**     
dce0: 20 20 20 20 20 6c 61 73 74 20 69 6e 73 65 72 74       last insert
dcf0: 20 72 6f 77 69 64 2e 0a 2a 2f 0a 73 71 6c 69 74   rowid..*/.sqlit
dd00: 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
dd10: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
dd20: 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
dd30: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
dd40: 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
dd50: 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
dd60: 20 7b 48 31 32 32 34 30 7d 20 3c 53 31 30 36 30   {H12240} <S1060
dd70: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  0>.**.** This fu
dd80: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
dd90: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
dda0: 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
ddb0: 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  were changed.** 
ddc0: 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  or inserted or d
ddd0: 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
dde0: 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
ddf0: 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  leted SQL statem
de00: 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64  ent.** on the [d
de10: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
de20: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
de30: 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
de40: 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68  eter..** Only ch
de50: 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64  anges that are d
de60: 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65  irectly specifie
de70: 64 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c  d by the INSERT,
de80: 20 55 50 44 41 54 45 2c 0a 2a 2a 20 6f 72 20 44   UPDATE,.** or D
de90: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
dea0: 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75  are counted.  Au
deb0: 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20  xiliary changes 
dec0: 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69  caused by.** tri
ded0: 67 67 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f  ggers are not co
dee0: 75 6e 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b  unted. Use the [
def0: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
df00: 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
df10: 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65  n.** to find the
df20: 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
df30: 20 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69   changes includi
df40: 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ng changes cause
df50: 64 20 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a  d by triggers..*
df60: 2a 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68 61 6e  *.** A "row chan
df70: 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20  ge" is a change 
df80: 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  to a single row 
df90: 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c  of a single tabl
dfa0: 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61  e.** caused by a
dfb0: 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45  n INSERT, DELETE
dfc0: 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74  , or UPDATE stat
dfd0: 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61  ement.  Rows tha
dfe0: 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64  t.** are changed
dff0: 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73   as side effects
e000: 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73   of REPLACE cons
e010: 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
e020: 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20  n,.** rollback, 
e030: 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
e040: 2c 20 44 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72  , DROP TABLE, or
e050: 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a   by any other.**
e060: 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e   mechanisms do n
e070: 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65  ot count as dire
e080: 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a  ct row changes..
e090: 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72  **.** A "trigger
e0a0: 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73   context" is a s
e0b0: 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f  cope of executio
e0c0: 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e  n that begins an
e0d0: 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74  d.** ends with t
e0e0: 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 74  he script of a t
e0f0: 72 69 67 67 65 72 2e 20 20 4d 6f 73 74 20 53 51  rigger.  Most SQ
e100: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
e110: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75  .** evaluated ou
e120: 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69  tside of any tri
e130: 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74  gger.  This is t
e140: 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a  he "top level".*
e150: 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
e160: 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72  t.  If a trigger
e170: 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20   fires from the 
e180: 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20  top level, a.** 
e190: 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
e1a0: 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66  ext is entered f
e1b0: 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20  or the duration 
e1c0: 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74  of that one.** t
e1d0: 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67  rigger.  Subtrig
e1e0: 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63  gers create subc
e1f0: 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69  ontexts for thei
e200: 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  r duration..**.*
e210: 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * Calling [sqlit
e220: 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73  e3_exec()] or [s
e230: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
e240: 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a  ecursively does.
e250: 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20  ** not create a 
e260: 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
e270: 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ext..**.** This 
e280: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
e290: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
e2a0: 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
e2b0: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74  s in the.** most
e2c0: 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
e2d0: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
e2e0: 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
e2f0: 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74  in the same.** t
e300: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
e310: 2a 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e  **.** Thus, when
e320: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
e330: 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73   top level, this
e340: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
e350: 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
e360: 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  of changes in th
e370: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
e380: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
e390: 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
e3a0: 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74  also occurred at
e3b0: 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20   the top level. 
e3c0: 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79   Within the body
e3d0: 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a   of a trigger,.*
e3e0: 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  * the sqlite3_ch
e3f0: 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63  anges() interfac
e400: 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
e410: 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
e420: 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73  er of.** changes
e430: 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
e440: 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
e450: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
e460: 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
e470: 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
e480: 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61  e body of the sa
e490: 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48  me trigger..** H
e4a0: 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62  owever, the numb
e4b0: 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  er returned does
e4c0: 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
e4d0: 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62  nges.** caused b
e4e0: 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69  y subtriggers si
e4f0: 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74  nce those have t
e500: 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74  heir own context
e510: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
e520: 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f  mplements the co
e530: 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52  mmand "DELETE FR
e540: 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75  OM table" withou
e550: 74 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65  t a WHERE clause
e560: 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20  .** by dropping 
e570: 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74  and recreating t
e580: 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73  he table.  (This
e590: 20 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20   is much faster 
e5a0: 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68  than going.** th
e5b0: 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69  rough and deleti
e5c0: 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c  ng individual el
e5d0: 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20  ements from the 
e5e0: 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65  table.)  Because
e5f0: 20 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69   of this.** opti
e600: 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65  mization, the de
e610: 6c 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45  letions in "DELE
e620: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61  TE FROM table" a
e630: 72 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67  re not row chang
e640: 65 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e  es and.** will n
e650: 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79  ot be counted by
e660: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
e670: 6e 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74  nges() or [sqlit
e680: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
e690: 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ()].** functions
e6a0: 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
e6b0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c  the number of el
e6c0: 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65  ements that were
e6d0: 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69   originally.** i
e6e0: 6e 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f  n the table.  To
e6f0: 20 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65   get an accurate
e700: 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75   count of the nu
e710: 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c  mber of rows del
e720: 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45  eted, use.** "DE
e730: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20  LETE FROM table 
e740: 57 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64  WHERE 1" instead
e750: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
e760: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34  TS:.**.** {H1224
e770: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
e780: 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74  changes()] funct
e790: 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e  ion shall return
e7a0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
e7b0: 2a 20 20 20 20 20 20 20 20 20 20 72 6f 77 20 63  *          row c
e7c0: 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
e7d0: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
e7e0: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
e7f0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
e800: 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
e810: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
e820: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e830: 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
e840: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
e850: 20 6f 72 20 68 69 67 68 65 72 20 74 72 69 67 67   or higher trigg
e860: 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a  er context, or z
e870: 65 72 6f 20 69 66 20 74 68 65 72 65 20 68 61 76  ero if there hav
e880: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f  e.**          no
e890: 74 20 62 65 65 6e 20 61 6e 79 20 71 75 61 6c 69  t been any quali
e8a0: 66 79 69 6e 67 20 72 6f 77 20 63 68 61 6e 67 65  fying row change
e8b0: 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34 33  s..**.** {H12243
e8c0: 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  } Statements of 
e8d0: 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45  the form "DELETE
e8e0: 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22   FROM tablename"
e8f0: 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20   with no.**     
e900: 20 20 20 20 20 57 48 45 52 45 20 63 6c 61 75 73       WHERE claus
e910: 65 20 73 68 61 6c 6c 20 63 61 75 73 65 20 73 75  e shall cause su
e920: 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
e930: 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
e940: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
e950: 5d 20 74 6f 20 72 65 74 75 72 6e 20 7a 65 72 6f  ] to return zero
e960: 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
e970: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
e980: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6f  number of rows o
e990: 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65  riginally in the
e9a0: 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 53   table..**.** AS
e9b0: 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  SUMPTIONS:.**.**
e9c0: 20 7b 41 31 32 32 35 32 7d 20 49 66 20 61 20 73   {A12252} If a s
e9d0: 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
e9e0: 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
e9f0: 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
ea00: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
ea10: 20 20 20 20 20 20 20 20 20 77 68 69 6c 65 20 5b           while [
ea20: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
ea30: 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
ea40: 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
ea50: 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  urned.**        
ea60: 20 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62    is unpredictab
ea70: 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
ea80: 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
ea90: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71  lite3_changes(sq
eaa0: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
eab0: 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20  CAPI3REF: Total 
eac0: 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
ead0: 6f 64 69 66 69 65 64 20 7b 48 31 32 32 36 30 7d  odified {H12260}
eae0: 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10600>.**.** 
eaf0: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
eb00: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
eb10: 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20   of row changes 
eb20: 63 61 75 73 65 64 20 62 79 20 49 4e 53 45 52 54  caused by INSERT
eb30: 2c 0a 2a 2a 20 55 50 44 41 54 45 20 6f 72 20 44  ,.** UPDATE or D
eb40: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73  ELETE statements
eb50: 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61   since the [data
eb60: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
eb70: 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20   was opened..** 
eb80: 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75 64  The count includ
eb90: 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 20 66  es all changes f
eba0: 72 6f 6d 20 61 6c 6c 20 74 72 69 67 67 65 72 20  rom all trigger 
ebb0: 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f 77 65 76  contexts.  Howev
ebc0: 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74  er,.** the count
ebd0: 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
ebe0: 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74  e changes used t
ebf0: 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 52 45 50 4c  o implement REPL
ec00: 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c  ACE constraints,
ec10: 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73  .** do rollbacks
ec20: 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73   or ABORT proces
ec30: 73 69 6e 67 2c 20 6f 72 20 44 52 4f 50 20 74 61  sing, or DROP ta
ec40: 62 6c 65 20 70 72 6f 63 65 73 73 69 6e 67 2e 0a  ble processing..
ec50: 2a 2a 20 54 68 65 20 63 68 61 6e 67 65 73 20 61  ** The changes a
ec60: 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73 6f  re counted as so
ec70: 6f 6e 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  on as the statem
ec80: 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74  ent that makes t
ec90: 68 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c 65  hem is.** comple
eca0: 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74  ted (when the st
ecb0: 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69  atement handle i
ecc0: 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
ecd0: 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
ece0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
ecf0: 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a  alize()])..**.**
ed00: 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e   SQLite implemen
ed10: 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22  ts the command "
ed20: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
ed30: 65 22 20 77 69 74 68 6f 75 74 20 61 20 57 48 45  e" without a WHE
ed40: 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20  RE clause.** by 
ed50: 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63  dropping and rec
ed60: 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c  reating the tabl
ed70: 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75 63  e.  (This is muc
ed80: 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f  h faster than go
ed90: 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  ing.** through a
eda0: 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69  nd deleting indi
edb0: 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20  vidual elements 
edc0: 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 29  from the table.)
edd0: 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 69    Because of thi
ede0: 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f  s.** optimizatio
edf0: 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e 73  n, the deletions
ee00: 20 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f 4d   in "DELETE FROM
ee10: 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74 20   table" are not 
ee20: 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64 0a  row changes and.
ee30: 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63  ** will not be c
ee40: 6f 75 6e 74 65 64 20 62 79 20 74 68 65 20 73 71  ounted by the sq
ee50: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
ee60: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  or [sqlite3_tota
ee70: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20  l_changes()].** 
ee80: 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61 72  functions, regar
ee90: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d  dless of the num
eea0: 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20  ber of elements 
eeb0: 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e  that were origin
eec0: 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74  ally.** in the t
eed0: 61 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61 6e  able.  To get an
eee0: 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20   accurate count 
eef0: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
ef00: 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75   rows deleted, u
ef10: 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52  se.** "DELETE FR
ef20: 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31  OM table WHERE 1
ef30: 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a  " instead..**.**
ef40: 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
ef50: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
ef60: 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
ef70: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
ef80: 2a 0a 2a 2a 20 7b 48 31 32 32 36 31 7d 20 54 68  *.** {H12261} Th
ef90: 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
efa0: 5f 63 68 61 6e 67 65 73 28 29 5d 20 72 65 74 75  _changes()] retu
efb0: 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  rns the total nu
efc0: 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  mber.**         
efd0: 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20   of row changes 
efe0: 63 61 75 73 65 64 20 62 79 20 49 4e 53 45 52 54  caused by INSERT
eff0: 2c 20 55 50 44 41 54 45 2c 20 61 6e 64 2f 6f 72  , UPDATE, and/or
f000: 20 44 45 4c 45 54 45 0a 2a 2a 20 20 20 20 20 20   DELETE.**      
f010: 20 20 20 20 73 74 61 74 65 6d 65 6e 74 73 20 6f      statements o
f020: 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
f030: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
f040: 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20 20 20 20 20  , in any.**     
f050: 20 20 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e       trigger con
f060: 74 65 78 74 2c 20 73 69 6e 63 65 20 74 68 65 20  text, since the 
f070: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f080: 69 6f 6e 20 77 61 73 20 63 72 65 61 74 65 64 2e  ion was created.
f090: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 36 33 7d 20  .**.** {H12263} 
f0a0: 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 74 68  Statements of th
f0b0: 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45 20 46  e form "DELETE F
f0c0: 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20 77  ROM tablename" w
f0d0: 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20  ith no.**       
f0e0: 20 20 20 57 48 45 52 45 20 63 6c 61 75 73 65 20     WHERE clause 
f0f0: 73 68 61 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65  shall not change
f100: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
f110: 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ned.**          
f120: 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  by [sqlite3_tota
f130: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 2e 0a 2a 2a  l_changes()]..**
f140: 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a  .** ASSUMPTIONS:
f150: 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 36 34 7d 20  .**.** {A12264} 
f160: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
f170: 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
f180: 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
f190: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f1a0: 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  on.**          w
f1b0: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f  hile [sqlite3_to
f1c0: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
f1d0: 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
f1e0: 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20  he value.**     
f1f0: 20 20 20 20 20 72 65 74 75 72 6e 65 64 20 69 73       returned is
f200: 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
f210: 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
f220: 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
f230: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
f240: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
f250: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
f260: 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
f270: 6e 69 6e 67 20 51 75 65 72 79 20 7b 48 31 32 32  ning Query {H122
f280: 37 30 7d 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a  70} <S30500>.**.
f290: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
f2a0: 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
f2b0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
f2c0: 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
f2d0: 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
f2e0: 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
f2f0: 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
f300: 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
f310: 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
f320: 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
f330: 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
f340: 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
f350: 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
f360: 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
f370: 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
f380: 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
f390: 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
f3a0: 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ately..**.** It 
f3b0: 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
f3c0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
f3d0: 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
f3e0: 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
f3f0: 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
f400: 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
f410: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
f420: 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
f430: 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
f440: 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
f450: 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
f460: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f470: 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
f480: 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
f490: 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
f4a0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
f4b0: 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
f4c0: 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
f4d0: 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
f4e0: 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
f4f0: 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
f500: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
f510: 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
f520: 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
f530: 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
f540: 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
f550: 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
f560: 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
f570: 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
f580: 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
f590: 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
f5a0: 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
f5b0: 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
f5c0: 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69  PT]..** If the i
f5d0: 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
f5e0: 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
f5f0: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
f600: 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
f610: 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
f620: 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
f630: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
f640: 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
f650: 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
f660: 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
f670: 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ally..**.** A ca
f680: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
f690: 74 65 72 72 75 70 74 28 29 20 68 61 73 20 6e 6f  terrupt() has no
f6a0: 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
f6b0: 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
f6c0: 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
f6d0: 74 65 72 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ter sqlite3_inte
f6e0: 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
f6f0: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
f700: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 31  S:.**.** {H12271
f710: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  } The [sqlite3_i
f720: 6e 74 65 72 72 75 70 74 28 29 5d 20 69 6e 74 65  nterrupt()] inte
f730: 72 66 61 63 65 20 77 69 6c 6c 20 66 6f 72 63 65  rface will force
f740: 20 61 6c 6c 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20   all running.** 
f750: 20 20 20 20 20 20 20 20 20 53 51 4c 20 73 74 61           SQL sta
f760: 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
f770: 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ed with the same
f780: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
f790: 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
f7a0: 20 74 6f 20 68 61 6c 74 20 61 66 74 65 72 20 70   to halt after p
f7b0: 72 6f 63 65 73 73 69 6e 67 20 61 74 20 6d 6f 73  rocessing at mos
f7c0: 74 20 6f 6e 65 20 61 64 64 69 74 69 6f 6e 61 6c  t one additional
f7d0: 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
f7e0: 0a 2a 2a 20 7b 48 31 32 32 37 32 7d 20 41 6e 79  .** {H12272} Any
f7f0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
f800: 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
f810: 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 69  ed by [sqlite3_i
f820: 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20  nterrupt()].**  
f830: 20 20 20 20 20 20 20 20 77 69 6c 6c 20 72 65 74          will ret
f840: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
f850: 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53  RRUPT]..**.** AS
f860: 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  SUMPTIONS:.**.**
f870: 20 7b 41 31 32 32 37 39 7d 20 49 66 20 74 68 65   {A12279} If the
f880: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
f890: 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c  tion closes whil
f8a0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  e [sqlite3_inter
f8b0: 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20  rupt()].**      
f8c0: 20 20 20 20 69 73 20 72 75 6e 6e 69 6e 67 20 74      is running t
f8d0: 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77  hen bad things w
f8e0: 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65  ill likely happe
f8f0: 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  n..*/.void sqlit
f900: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
f910: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
f920: 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
f930: 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
f940: 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
f950: 74 65 20 7b 48 31 30 35 31 30 7d 20 3c 53 37 30  te {H10510} <S70
f960: 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  200>.**.** These
f970: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
f980: 65 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64  eful for command
f990: 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
f9a0: 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
f9b0: 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
f9c0: 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
f9d0: 74 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65  to form complete
f9e0: 20 61 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74   a SQL statement
f9f0: 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
fa00: 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
fa10: 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
fa20: 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
fa30: 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
fa40: 70 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20  parsing.  These 
fa50: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
fa60: 74 72 75 65 20 69 66 20 74 68 65 20 69 6e 70 75  true if the inpu
fa70: 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
fa80: 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
fa90: 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
faa0: 6e 74 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74  nt.  A statement
fab0: 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
fac0: 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
fad0: 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
fae0: 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
faf0: 6e 64 20 69 73 20 6e 6f 74 20 61 20 66 72 61 67  nd is not a frag
fb00: 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45  ment of a.** CRE
fb10: 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
fb20: 65 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f  ement.  Semicolo
fb30: 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65  ns that are embe
fb40: 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73  dded within.** s
fb50: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f  tring literals o
fb60: 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66  r quoted identif
fb70: 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d  ier names or com
fb80: 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ments are not.**
fb90: 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b   independent tok
fba0: 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61  ens (they are pa
fbb0: 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20  rt of the token 
fbc0: 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72  in which they ar
fbd0: 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61  e.** embedded) a
fbe0: 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63  nd thus do not c
fbf0: 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d  ount as a statem
fc00: 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ent terminator..
fc10: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
fc20: 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
fc30: 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
fc40: 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
fc50: 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
fc60: 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
fc70: 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
fc80: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
fc90: 2a 20 7b 48 31 30 35 31 31 7d 20 41 20 73 75 63  * {H10511} A suc
fca0: 63 65 73 73 66 75 6c 20 65 76 61 6c 75 61 74 69  cessful evaluati
fcb0: 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63  on of [sqlite3_c
fcc0: 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 0a 2a 2a  omplete()] or.**
fcd0: 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
fce0: 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
fcf0: 20 66 75 6e 63 74 69 6f 6e 73 20 73 68 61 6c 6c   functions shall
fd00: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
fd10: 75 72 6e 20 61 20 6e 75 6d 65 72 69 63 20 31 20  urn a numeric 1 
fd20: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
fd30: 68 65 20 6c 61 73 74 20 6e 6f 6e 2d 77 68 69 74  he last non-whit
fd40: 65 73 70 61 63 65 0a 2a 2a 20 20 20 20 20 20 20  espace.**       
fd50: 20 20 20 74 6f 6b 65 6e 20 69 6e 20 74 68 65 69     token in thei
fd60: 72 20 69 6e 70 75 74 20 69 73 20 61 20 73 65 6d  r input is a sem
fd70: 69 63 6f 6c 6f 6e 20 74 68 61 74 20 69 73 20 6e  icolon that is n
fd80: 6f 74 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ot in between.**
fd90: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 42 45            the BE
fda0: 47 49 4e 20 61 6e 64 20 45 4e 44 20 6f 66 20 61  GIN and END of a
fdb0: 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
fdc0: 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
fdd0: 20 7b 48 31 30 35 31 32 7d 20 49 66 20 61 20 6d   {H10512} If a m
fde0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
fdf0: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
fe00: 72 69 6e 67 20 61 6e 20 69 6e 76 6f 63 61 74 69  ring an invocati
fe10: 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  on.**          o
fe20: 66 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  f [sqlite3_compl
fe30: 65 74 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ete()] or [sqlit
fe40: 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
fe50: 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20   then the.**    
fe60: 20 20 20 20 20 20 72 6f 75 74 69 6e 65 20 73 68        routine sh
fe70: 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  all return [SQLI
fe80: 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
fe90: 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a   ASSUMPTIONS:.**
fea0: 0a 2a 2a 20 7b 41 31 30 35 31 32 7d 20 54 68 65  .** {A10512} The
feb0: 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
fec0: 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d  e3_complete()] m
fed0: 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
fee0: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20  rminated.**     
fef0: 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e       UTF-8 strin
ff00: 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 33  g..**.** {A10513
ff10: 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  } The input to [
ff20: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
ff30: 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  16()] must be a 
ff40: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
ff50: 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d  **          UTF-
ff60: 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
ff70: 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
ff80: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
ff90: 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
ffa0: 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71  ar *sql);.int sq
ffb0: 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
ffc0: 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
ffd0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
ffe0: 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
fff0: 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
10000 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
10010 72 6f 72 73 20 7b 48 31 32 33 31 30 7d 20 3c 53  rors {H12310} <S
10020 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  40400>.**.** Thi
10030 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
10040 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
10050 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  on that might be
10060 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
10070 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
10080 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
10090 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
100a0 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68   that another th
100b0 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
100c0 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a  ss has locked..*
100d0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79  *.** If the busy
100e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
100f0 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  L, then [SQLITE_
10100 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
10110 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
10120 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
10130 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20  mmediately upon 
10140 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65  encountering the
10150 20 6c 6f 63 6b 2e 20 49 66 20 74 68 65 20 62 75   lock. If the bu
10160 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  sy callback.** i
10170 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
10180 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 69   the callback wi
10190 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ll be invoked wi
101a0 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
101b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
101c0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
101d0 65 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  e handler is a c
101e0 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
101f0 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
10200 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
10210 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
10220 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
10230 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ).  The second a
10240 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
10250 65 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  e handler callba
10260 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
10270 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
10280 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
10290 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
102a0 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63  ked for this loc
102b0 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 49 66 20  king event.  If 
102c0 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c  the.** busy call
102d0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20  back returns 0, 
102e0 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e  then no addition
102f0 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20  al attempts are 
10300 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73  made to.** acces
10310 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
10320 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  nd [SQLITE_BUSY]
10330 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
10340 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65  R_BLOCKED] is re
10350 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68  turned..** If th
10360 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
10370 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
10380 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70  n another attemp
10390 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20  t.** is made to 
103a0 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
103b0 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  e for reading an
103c0 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
103d0 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
103e0 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
103f0 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
10400 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
10410 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
10420 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
10430 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
10440 6e 74 69 6f 6e 2e 20 49 66 20 53 51 4c 69 74 65  ntion. If SQLite
10450 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
10460 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
10470 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
10480 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
10490 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
104a0 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
104b0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
104c0 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  SY].** or [SQLIT
104d0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
104e0 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f   instead of invo
104f0 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61  king the busy ha
10500 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64  ndler..** Consid
10510 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
10520 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
10530 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
10540 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
10550 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
10560 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
10570 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
10580 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
10590 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
105a0 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
105b0 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
105c0 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
105d0 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
105e0 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
105f0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
10600 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
10610 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
10620 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
10630 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
10640 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
10650 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
10660 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
10670 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
10680 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
10690 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
106a0 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
106b0 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
106c0 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
106d0 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
106e0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
106f0 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
10700 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
10710 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
10720 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
10730 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
10740 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
10750 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
10760 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
10770 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
10780 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66  d..**.** The def
10790 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
107a0 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
107b0 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55  * The [SQLITE_BU
107c0 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e  SY] error is con
107d0 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54  verted to [SQLIT
107e0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
107f0 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
10800 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65  is in the middle
10810 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e   of a large tran
10820 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c  saction where al
10830 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73  l the.** changes
10840 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e   will not fit in
10850 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  to the in-memory
10860 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20   cache.  SQLite 
10870 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20  will.** already 
10880 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20  hold a RESERVED 
10890 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61  lock on the data
108a0 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69  base file, but i
108b0 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72  t needs.** to pr
108c0 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20  omote this lock 
108d0 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20  to EXCLUSIVE so 
108e0 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c  that it can spil
108f0 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73  l cache.** pages
10900 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
10910 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20  se file without 
10920 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65  harm to concurre
10930 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20  nt.** readers.  
10940 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  If it is unable 
10950 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c  to promote the l
10960 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e  ock, then the in
10970 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65  -memory.** cache
10980 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e   will be left in
10990 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74   an inconsistent
109a0 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68   state and so th
109b0 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
109c0 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d  is promoted from
109d0 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20   the relatively 
109e0 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42  benign [SQLITE_B
109f0 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d  USY] to.** the m
10a00 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49  ore severe [SQLI
10a10 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
10a20 5d 2e 20 20 54 68 69 73 20 65 72 72 6f 72 20 63  ].  This error c
10a30 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a  ode promotion.**
10a40 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d   forces an autom
10a50 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66  atic rollback of
10a60 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53   the changes.  S
10a70 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65  ee the.** <a hre
10a80 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69  f="/cvstrac/wiki
10a90 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ?p=CorruptionFol
10aa0 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22  lowingBusyError"
10ab0 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46  >.** CorruptionF
10ac0 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
10ad0 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20  r</a> wiki page 
10ae0 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e  for a discussion
10af0 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20   of why.** this 
10b00 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a  is important..**
10b10 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e  .** There can on
10b20 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
10b30 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
10b40 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ned for each.** 
10b50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10b60 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20  tion].  Setting 
10b70 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
10b80 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a  er clears any.**
10b90 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
10ba0 68 61 6e 64 6c 65 72 2e 20 20 4e 6f 74 65 20 74  handler.  Note t
10bb0 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
10bc0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
10bd0 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73  t()].** will als
10be0 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74  o set or clear t
10bf0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
10c00 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
10c10 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 31  S:.**.** {H12311
10c20 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
10c30 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 43 2c  usy_handler(D,C,
10c40 41 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61  A)] function sha
10c50 6c 6c 20 72 65 70 6c 61 63 65 0a 2a 2a 20 20 20  ll replace.**   
10c60 20 20 20 20 20 20 20 62 75 73 79 20 63 61 6c 6c         busy call
10c70 62 61 63 6b 20 69 6e 20 74 68 65 20 5b 64 61 74  back in the [dat
10c80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10c90 5d 20 44 20 77 69 74 68 20 61 20 6e 65 77 0a 2a  ] D with a new.*
10ca0 2a 20 20 20 20 20 20 20 20 20 20 61 20 6e 65 77  *          a new
10cb0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 43 20   busy handler C 
10cc0 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  and application 
10cd0 64 61 74 61 20 70 6f 69 6e 74 65 72 20 41 2e 0a  data pointer A..
10ce0 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 32 7d 20 4e  **.** {H12312} N
10cf0 65 77 6c 79 20 63 72 65 61 74 65 64 20 5b 64 61  ewly created [da
10d00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10d10 6e 73 5d 20 73 68 61 6c 6c 20 68 61 76 65 20 61  ns] shall have a
10d20 20 62 75 73 79 0a 2a 2a 20 20 20 20 20 20 20 20   busy.**        
10d30 20 20 68 61 6e 64 6c 65 72 20 6f 66 20 4e 55 4c    handler of NUL
10d40 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 34  L..**.** {H12314
10d50 7d 20 57 68 65 6e 20 74 77 6f 20 6f 72 20 6d 6f  } When two or mo
10d60 72 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  re [database con
10d70 6e 65 63 74 69 6f 6e 73 5d 20 73 68 61 72 65 20  nections] share 
10d80 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  a.**          [s
10d90 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
10da0 61 72 65 64 5f 63 61 63 68 65 20 7c 20 63 6f 6d  ared_cache | com
10db0 6d 6f 6e 20 63 61 63 68 65 5d 2c 0a 2a 2a 20 20  mon cache],.**  
10dc0 20 20 20 20 20 20 20 20 74 68 65 20 62 75 73 79          the busy
10dd0 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65   handler for the
10de0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
10df0 74 69 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20 75  tion currently u
10e00 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
10e10 20 74 68 65 20 63 61 63 68 65 20 73 68 61 6c 6c   the cache shall
10e20 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
10e30 20 74 68 65 20 63 61 63 68 65 20 65 6e 63 6f 75   the cache encou
10e40 6e 74 65 72 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a  nters a lock..**
10e50 0a 2a 2a 20 7b 48 31 32 33 31 36 7d 20 49 66 20  .** {H12316} If 
10e60 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  a busy handler c
10e70 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
10e80 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 53  zero, then the S
10e90 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
10ea0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74  **          that
10eb0 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 20 6c 6f   provoked the lo
10ec0 63 6b 69 6e 67 20 65 76 65 6e 74 20 73 68 61 6c  cking event shal
10ed0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
10ee0 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  _BUSY]..**.** {H
10ef0 31 32 33 31 38 7d 20 53 51 4c 69 74 65 20 73 68  12318} SQLite sh
10f00 61 6c 6c 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  all invokes the 
10f10 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77 69 74  busy handler wit
10f20 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20  h two arguments 
10f30 77 68 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 20  which.**        
10f40 20 20 61 72 65 20 61 20 63 6f 70 79 20 6f 66 20    are a copy of 
10f50 74 68 65 20 70 6f 69 6e 74 65 72 20 73 75 70 70  the pointer supp
10f60 6c 69 65 64 20 62 79 20 74 68 65 20 33 72 64 20  lied by the 3rd 
10f70 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
10f80 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
10f90 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
10fa0 5d 20 61 6e 64 20 61 20 63 6f 75 6e 74 20 6f 66  ] and a count of
10fb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
10fc0 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rior.**         
10fd0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
10fe0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
10ff0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f   for the same lo
11000 63 6b 69 6e 67 20 65 76 65 6e 74 2e 0a 2a 2a 0a  cking event..**.
11010 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a  ** ASSUMPTIONS:.
11020 2a 2a 0a 2a 2a 20 7b 41 31 32 33 31 39 7d 20 41  **.** {A12319} A
11030 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75   busy handler mu
11040 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
11050 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
11060 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
11070 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74   or [prepared st
11080 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e  atement] that in
11090 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
110a0 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73  andler..*/.int s
110b0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
110c0 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
110d0 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c  t(*)(void*,int),
110e0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
110f0 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20  CAPI3REF: Set A 
11100 42 75 73 79 20 54 69 6d 65 6f 75 74 20 7b 48 31  Busy Timeout {H1
11110 32 33 34 30 7d 20 3c 53 34 30 34 30 30 3e 0a 2a  2340} <S40400>.*
11120 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
11130 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65  e sets a [sqlite
11140 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c  3_busy_handler |
11150 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74   busy handler] t
11160 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f  hat sleeps.** fo
11170 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d  r a specified am
11180 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65  ount of time whe
11190 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63  n a table is loc
111a0 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65  ked.  The handle
111b0 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20  r.** will sleep 
111c0 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
111d0 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d  ntil at least "m
111e0 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
111f0 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68  of sleeping.** h
11200 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e  ave accumulated.
11210 20 7b 48 31 32 33 34 33 7d 20 41 66 74 65 72 20   {H12343} After 
11220 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
11230 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
11240 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
11250 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
11260 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
11270 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
11280 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
11290 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
112a0 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a  R_BLOCKED]..**.*
112b0 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72  * Calling this r
112c0 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
112d0 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
112e0 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
112f0 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20  ro.** turns off 
11300 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  all busy handler
11310 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63  s..**.** There c
11320 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
11330 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
11340 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
11350 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
11360 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61  onnection] any a
11370 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
11380 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
11390 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
113a0 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
113b0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
113c0 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
113d0 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
113e0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
113f0 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
11400 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
11410 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
11420 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 31  S:.**.** {H12341
11430 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
11440 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 66  usy_timeout()] f
11450 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 6f 76  unction shall ov
11460 65 72 72 69 64 65 20 61 6e 79 20 70 72 69 6f 72  erride any prior
11470 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
11480 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
11490 75 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ut()] or [sqlite
114a0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
114b0 5d 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  ] setting.**    
114c0 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d        on the sam
114d0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
114e0 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  ection]..**.** {
114f0 48 31 32 33 34 33 7d 20 49 66 20 74 68 65 20 32  H12343} If the 2
11500 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
11510 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
11520 6d 65 6f 75 74 28 29 5d 20 69 73 20 6c 65 73 73  meout()] is less
11530 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20   than.**        
11540 20 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65    or equal to ze
11550 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 62 75 73  ro, then the bus
11560 79 20 68 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20  y handler shall 
11570 62 65 20 63 6c 65 61 72 65 64 20 73 6f 20 74 68  be cleared so th
11580 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  at.**          a
11590 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 6c 6f  ll subsequent lo
115a0 63 6b 69 6e 67 20 65 76 65 6e 74 73 20 69 6d 6d  cking events imm
115b0 65 64 69 61 74 65 6c 79 20 72 65 74 75 72 6e 20  ediately return 
115c0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a  [SQLITE_BUSY]..*
115d0 2a 0a 2a 2a 20 7b 48 31 32 33 34 34 7d 20 49 66  *.** {H12344} If
115e0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
115f0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
11600 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69  usy_timeout()] i
11610 73 20 61 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20  s a positive.** 
11620 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
11630 4e 2c 20 74 68 65 6e 20 61 20 62 75 73 79 20 68  N, then a busy h
11640 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20 62 65 20  andler shall be 
11650 73 65 74 20 74 68 61 74 20 72 65 70 65 61 74 65  set that repeate
11660 64 6c 79 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20  dly calls.**    
11670 20 20 20 20 20 20 74 68 65 20 78 53 6c 65 65 70        the xSleep
11680 28 29 20 6d 65 74 68 6f 64 20 69 6e 20 74 68 65  () method in the
11690 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
116a0 56 46 53 20 69 6e 74 65 72 66 61 63 65 5d 20 75  VFS interface] u
116b0 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ntil.**         
116c0 20 65 69 74 68 65 72 20 74 68 65 20 6c 6f 63 6b   either the lock
116d0 20 63 6c 65 61 72 73 20 6f 72 20 75 6e 74 69 6c   clears or until
116e0 20 74 68 65 20 63 75 6d 75 6c 61 74 69 76 65 20   the cumulative 
116f0 73 6c 65 65 70 20 74 69 6d 65 0a 2a 2a 20 20 20  sleep time.**   
11700 20 20 20 20 20 20 20 72 65 70 6f 72 74 65 64 20         reported 
11710 62 61 63 6b 20 62 79 20 78 53 6c 65 65 70 28 29  back by xSleep()
11720 20 65 78 63 65 65 64 73 20 4e 20 6d 69 6c 6c 69   exceeds N milli
11730 73 65 63 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20  seconds..*/.int 
11740 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
11750 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  eout(sqlite3*, i
11760 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  nt ms);../*.** C
11770 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69  API3REF: Conveni
11780 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f  ence Routines Fo
11790 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65  r Running Querie
117a0 73 20 7b 48 31 32 33 37 30 7d 20 3c 53 31 30 30  s {H12370} <S100
117b0 30 30 3e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  00>.**.** Defini
117c0 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
117d0 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
117e0 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
117f0 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
11800 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
11810 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
11820 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
11830 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
11840 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
11850 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
11860 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
11870 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
11880 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
11890 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
118a0 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
118b0 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
118c0 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
118d0 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
118e0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
118f0 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
11900 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
11910 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
11920 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
11930 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
11940 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
11950 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
11960 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
11970 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
11980 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
11990 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
119a0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
119b0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
119c0 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
119d0 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
119e0 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
119f0 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
11a00 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
11a10 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
11a20 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
11a30 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
11a40 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
11a50 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
11a60 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
11a70 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
11a80 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
11a90 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
11aa0 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
11ab0 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
11ac0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
11ad0 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
11ae0 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
11af0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
11b00 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
11b10 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
11b20 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
11b30 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
11b40 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
11b50 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
11b60 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
11b70 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
11b80 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
11b90 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
11ba0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
11bb0 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
11bc0 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
11bd0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
11be0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e  ()]..**.** As an
11bf0 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
11c00 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
11c10 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
11c20 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
11c30 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
11c40 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
11c50 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
11c60 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
11c70 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
11c80 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
11c90 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
11ca0 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
11cb0 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
11cc0 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
11cd0 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
11ce0 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
11cf0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
11d00 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
11d10 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
11d20 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
11d30 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
11d40 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
11d50 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
11d60 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
11d70 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
11d80 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
11d90 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
11da0 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
11db0 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
11dc0 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
11dd0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
11de0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
11df0 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
11e00 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
11e10 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
11e20 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
11e30 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
11e40 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
11e50 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
11e60 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
11e70 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
11e80 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
11e90 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
11ea0 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
11eb0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
11ec0 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
11ed0 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
11ee0 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
11ef0 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
11f00 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
11f10 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
11f20 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74  et_table() funct
11f30 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e  ion evaluates on
11f40 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d  e or more.** sem
11f50 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64  icolon-separated
11f60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
11f70 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  in the zero-term
11f80 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20  inated UTF-8.** 
11f90 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e  string of its 2n
11fa0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 74  d parameter.  It
11fb0 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
11fc0 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a  t table to the.*
11fd0 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20  * pointer given 
11fe0 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  in its 3rd param
11ff0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  eter..**.** Afte
12000 72 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  r the calling fu
12010 6e 63 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  nction has finis
12020 68 65 64 20 75 73 69 6e 67 20 74 68 65 20 72 65  hed using the re
12030 73 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64 0a  sult, it should.
12040 2a 2a 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  ** pass the poin
12050 74 65 72 20 74 6f 20 74 68 65 20 72 65 73 75 6c  ter to the resul
12060 74 20 74 61 62 6c 65 20 74 6f 20 73 71 6c 69 74  t table to sqlit
12070 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
12080 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
12090 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
120a0 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
120b0 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
120c0 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
120d0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
120e0 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
120f0 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
12100 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
12110 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
12120 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
12130 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
12140 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
12150 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
12160 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
12170 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
12180 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
12190 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
121a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
121b0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
121c0 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
121d0 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
121e0 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
121f0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
12200 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
12210 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
12220 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
12230 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
12240 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
12250 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
12260 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
12270 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
12280 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
12290 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
122a0 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
122b0 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
122c0 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
122d0 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
122e0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
122f0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
12300 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
12310 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
12320 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
12330 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
12340 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
12350 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a  _errmsg()]..**.*
12360 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
12370 0a 2a 2a 20 7b 48 31 32 33 37 31 7d 20 49 66 20  .** {H12371} If 
12380 61 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  a [sqlite3_get_t
12390 61 62 6c 65 28 29 5d 20 66 61 69 6c 73 20 61 20  able()] fails a 
123a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
123b0 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  n, then.**      
123c0 20 20 20 20 69 74 20 73 68 61 6c 6c 20 66 72 65      it shall fre
123d0 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
123e0 6c 65 20 75 6e 64 65 72 20 63 6f 6e 73 74 72 75  le under constru
123f0 63 74 69 6f 6e 2c 20 61 62 6f 72 74 20 74 68 65  ction, abort the
12400 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 71 75 65  .**          que
12410 72 79 20 69 6e 20 70 72 6f 63 65 73 73 2c 20 73  ry in process, s
12420 6b 69 70 20 61 6e 79 20 73 75 62 73 65 71 75 65  kip any subseque
12430 6e 74 20 71 75 65 72 69 65 73 2c 20 73 65 74 20  nt queries, set 
12440 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
12450 2a 70 61 7a 52 65 73 75 6c 74 20 6f 75 74 70 75  *pazResult outpu
12460 74 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c  t pointer to NUL
12470 4c 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  L and return [SQ
12480 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
12490 2a 2a 20 7b 48 31 32 33 37 33 7d 20 49 66 20 74  ** {H12373} If t
124a0 68 65 20 70 6e 43 6f 6c 75 6d 6e 20 70 61 72 61  he pnColumn para
124b0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
124c0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
124d0 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20  s not NULL.**   
124e0 20 20 20 20 20 20 20 74 68 65 6e 20 61 20 73 75         then a su
124f0 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
12500 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
12510 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 73 68 61  get_table()] sha
12520 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  ll.**          w
12530 72 69 74 65 20 74 68 65 20 6e 75 6d 62 65 72 20  rite the number 
12540 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
12550 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
12560 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20  sult set of the 
12570 71 75 65 72 79 20 69 6e 74 6f 20 2a 70 6e 43 6f  query into *pnCo
12580 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  lumn..**.** {H12
12590 33 37 34 7d 20 49 66 20 74 68 65 20 70 6e 52 6f  374} If the pnRo
125a0 77 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  w parameter to [
125b0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
125c0 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  e()] is not NULL
125d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
125e0 6e 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 69  n a successful i
125f0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
12600 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
12610 29 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20  )] shall.**     
12620 20 20 20 20 20 77 72 69 74 65 73 20 74 68 65 20       writes the 
12630 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69  number of rows i
12640 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
12650 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20    result set of 
12660 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a  the query into *
12670 70 6e 52 6f 77 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  pnRow..**.** {H1
12680 32 33 37 36 7d 20 41 20 73 75 63 63 65 73 73 66  2376} A successf
12690 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ul invocation of
126a0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
126b0 62 6c 65 28 29 5d 20 74 68 61 74 20 63 6f 6d 70  ble()] that comp
126c0 75 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  utes.**         
126d0 20 4e 20 72 6f 77 73 20 6f 66 20 72 65 73 75 6c   N rows of resul
126e0 74 20 77 69 74 68 20 43 20 63 6f 6c 75 6d 6e 73  t with C columns
126f0 20 70 65 72 20 72 6f 77 20 73 68 61 6c 6c 20 6d   per row shall m
12700 61 6b 65 20 2a 70 61 7a 52 65 73 75 6c 74 0a 2a  ake *pazResult.*
12710 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
12720 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20   to an array of 
12730 70 6f 69 6e 74 65 72 73 20 74 6f 20 28 4e 2b 31  pointers to (N+1
12740 29 2a 43 20 73 74 72 69 6e 67 73 20 77 68 65 72  )*C strings wher
12750 65 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 20  e the first.**  
12760 20 20 20 20 20 20 20 20 43 20 73 74 72 69 6e 67          C string
12770 73 20 61 72 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  s are column nam
12780 65 73 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66  es as obtained f
12790 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rom.**          
127a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
127b0 6e 61 6d 65 28 29 5d 20 61 6e 64 20 74 68 65 20  name()] and the 
127c0 72 65 73 74 20 61 72 65 20 63 6f 6c 75 6d 6e 20  rest are column 
127d0 72 65 73 75 6c 74 20 76 61 6c 75 65 73 0a 2a 2a  result values.**
127e0 20 20 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e            obtain
127f0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
12800 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
12810 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 39 7d 20  .**.** {H12379} 
12820 54 68 65 20 76 61 6c 75 65 73 20 69 6e 20 74 68  The values in th
12830 65 20 70 61 7a 52 65 73 75 6c 74 20 61 72 72 61  e pazResult arra
12840 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  y returned by [s
12850 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
12860 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
12870 73 68 61 6c 6c 20 72 65 6d 61 69 6e 20 76 61 6c  shall remain val
12880 69 64 20 75 6e 74 69 6c 20 63 6c 65 61 72 65 64  id until cleared
12890 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   by [sqlite3_fre
128a0 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
128b0 2a 20 7b 48 31 32 33 38 32 7d 20 57 68 65 6e 20  * {H12382} When 
128c0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
128d0 64 75 72 69 6e 67 20 65 76 61 6c 75 61 74 69 6f  during evaluatio
128e0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65  n of [sqlite3_ge
128f0 74 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 20 20  t_table()].**   
12900 20 20 20 20 20 20 20 74 68 65 20 66 75 6e 63 74         the funct
12910 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74 20 2a 70  ion shall set *p
12920 61 7a 52 65 73 75 6c 74 20 74 6f 20 4e 55 4c 4c  azResult to NULL
12930 2c 20 77 72 69 74 65 20 61 6e 20 65 72 72 6f 72  , write an error
12940 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20   message.**     
12950 20 20 20 20 20 69 6e 74 6f 20 6d 65 6d 6f 72 79       into memory
12960 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
12970 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
12980 5d 2c 20 6d 61 6b 65 0a 2a 2a 20 20 20 20 20 20  ], make.**      
12990 20 20 20 20 2a 2a 70 7a 45 72 72 6d 73 67 20 70      **pzErrmsg p
129a0 6f 69 6e 74 20 74 6f 20 74 68 61 74 20 65 72 72  oint to that err
129b0 6f 72 20 6d 65 73 73 61 67 65 2c 20 61 6e 64 20  or message, and 
129c0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 20 20 20 20  return a.**     
129d0 20 20 20 20 20 61 70 70 72 6f 70 72 69 61 74 65       appropriate
129e0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
129f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
12a00 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
12a10 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
12a20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
12a30 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
12a40 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
12a50 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
12a60 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
12a70 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
12a80 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
12a90 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
12aa0 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
12ab0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
12ac0 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
12ad0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
12ae0 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
12af0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
12b00 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
12b10 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
12b20 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
12b30 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
12b40 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
12b50 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
12b60 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
12b70 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
12b80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
12b90 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
12ba0 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
12bb0 63 74 69 6f 6e 73 20 7b 48 31 37 34 30 30 7d 20  ctions {H17400} 
12bc0 3c 53 37 30 30 30 30 3e 3c 53 32 30 30 30 30 3e  <S70000><S20000>
12bd0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
12be0 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 61 6c  tines are workal
12bf0 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69  ikes of the "pri
12c00 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66  ntf()" family of
12c10 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72   functions.** fr
12c20 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
12c30 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  C library..**.**
12c40 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72   The sqlite3_mpr
12c50 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
12c60 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
12c70 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
12c80 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
12c90 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
12ca0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
12cb0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
12cc0 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
12cd0 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
12ce0 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
12cf0 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
12d00 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
12d10 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f 75 74 69  ()].  Both routi
12d20 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
12d30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
12d40 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
12d50 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
12d60 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
12d70 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
12d80 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
12d90 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e  string..**.** In
12da0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
12db0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
12dc0 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
12dd0 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
12de0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
12df0 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
12e00 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
12e10 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
12e20 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
12e30 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
12e40 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
12e50 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
12e60 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
12e70 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
12e80 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
12e90 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
12ea0 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
12eb0 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
12ec0 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
12ed0 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
12ee0 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
12ef0 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
12f00 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
12f10 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
12f20 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f  lity.  Note also
12f30 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
12f40 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
12f50 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
12f60 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
12f70 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
12f80 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
12f90 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
12fa0 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
12fb0 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74 20 74  fer.  We admit t
12fc0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
12fd0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
12fe0 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
12ff0 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
13000 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
13010 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
13020 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
13030 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
13040 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
13050 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
13060 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
13070 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e  ty..**.** As lon
13080 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
13090 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
130a0 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
130b0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
130c0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
130d0 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
130e0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
130f0 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69 72 73  nated.  The firs
13100 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
13110 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
13120 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
13130 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
13140 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
13150 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
13160 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
13170 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
13180 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
13190 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
131a0 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
131b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
131c0 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d  tines all implem
131d0 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  ent some additio
131e0 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a  nal formatting.*
131f0 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61  * options that a
13200 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
13210 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73  nstructing SQL s
13220 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c  tatements..** Al
13230 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70  l of the usual p
13240 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69  rintf() formatti
13250 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79  ng options apply
13260 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20  .  In addition, 
13270 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20  there.** is are 
13280 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20  "%q", "%Q", and 
13290 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%z" options..**
132a0 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69 6f  .** The %q optio
132b0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20  n works like %s 
132c0 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74  in that it subst
132d0 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65  itutes a null-te
132e0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
132f0 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
13300 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
13310 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
13320 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
13330 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
13340 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
13350 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
13360 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f 75  literal.  By dou
13370 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
13380 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
13390 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
133a0 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
133b0 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
133c0 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
133d0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
133e0 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d  r example, assum
133f0 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72  e the string var
13400 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74  iable zText cont
13410 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
13420 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
13430 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
13440 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
13450 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
13460 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
13470 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
13480 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
13490 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
134a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
134b0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
134c0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
134d0 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
134e0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
134f0 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
13500 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
13510 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
13520 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
13530 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
13540 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
13550 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
13560 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
13570 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
13580 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
13590 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
135a0 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
135b0 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
135c0 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
135d0 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
135e0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
135f0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
13600 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
13610 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
13620 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
13630 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
13640 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
13650 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
13660 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
13670 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
13680 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
13690 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
136a0 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
136b0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
136c0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
136d0 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
136e0 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
136f0 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
13700 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
13710 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
13720 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
13730 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
13740 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
13750 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
13760 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79   should.** alway
13770 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
13780 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
13790 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
137a0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
137b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f  ..**.** The %Q o
137c0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
137d0 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
137e0 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
137f0 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
13800 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
13810 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
13820 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
13830 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
13840 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
13850 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
13860 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
13870 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
13880 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
13890 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
138a0 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f  otes) in place o
138b0 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e  f the %Q option.
138c0 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
138d0 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
138e0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
138f0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
13900 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
13910 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
13920 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
13930 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
13940 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
13950 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
13960 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
13970 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
13980 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
13990 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
139a0 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
139b0 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
139c0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
139d0 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
139e0 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
139f0 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
13a00 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
13a10 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
13a20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%z" formatting 
13a30 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61  option works exa
13a40 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20 77  ctly like "%s" w
13a50 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
13a60 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
13a70 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
13a80 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
13a90 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
13aa0 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
13ab0 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
13ac0 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
13ad0 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  tring. {END}.**.
13ae0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
13af0 2a 0a 2a 2a 20 7b 48 31 37 34 30 33 7d 20 20 54  *.** {H17403}  T
13b00 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69  he [sqlite3_mpri
13b10 6e 74 66 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ntf()] and [sqli
13b20 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 5d 20  te3_vmprintf()] 
13b30 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 20 20  interfaces.**   
13b40 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 65          return e
13b50 69 74 68 65 72 20 70 6f 69 6e 74 65 72 73 20 74  ither pointers t
13b60 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
13b70 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 20  d UTF-8 strings 
13b80 68 65 6c 64 20 69 6e 0a 2a 2a 20 20 20 20 20 20  held in.**      
13b90 20 20 20 20 20 6d 65 6d 6f 72 79 20 6f 62 74 61       memory obta
13ba0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
13bb0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
13bc0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 69 66  NULL pointers if
13bd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 20  .**           a 
13be0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
13bf0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 61 69 6c 73  _malloc()] fails
13c00 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 36 7d  ..**.** {H17406}
13c10 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73    The [sqlite3_s
13c20 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72  nprintf()] inter
13c30 66 61 63 65 20 77 72 69 74 65 73 20 61 20 7a 65  face writes a ze
13c40 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
13c50 20 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38             UTF-8
13c60 20 73 74 72 69 6e 67 20 69 6e 74 6f 20 74 68 65   string into the
13c70 20 62 75 66 66 65 72 20 70 6f 69 6e 74 65 64 20   buffer pointed 
13c80 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  to by the second
13c90 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
13ca0 20 20 20 20 20 20 20 20 70 72 6f 76 69 64 65 64          provided
13cb0 20 74 68 61 74 20 74 68 65 20 66 69 72 73 74 20   that the first 
13cc0 70 61 72 61 6d 65 74 65 72 20 69 73 20 67 72 65  parameter is gre
13cd0 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2e 0a  ater than zero..
13ce0 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 37 7d 20 20  **.** {H17407}  
13cf0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  The [sqlite3_snp
13d00 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61  rintf()] interfa
13d10 63 65 20 64 6f 65 73 20 6e 6f 74 20 77 72 69 74  ce does not writ
13d20 65 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a 20 20 20  e slots of.**   
13d30 20 20 20 20 20 20 20 20 69 74 73 20 6f 75 74 70          its outp
13d40 75 74 20 62 75 66 66 65 72 20 28 74 68 65 20 73  ut buffer (the s
13d50 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 29  econd parameter)
13d60 20 6f 75 74 73 69 64 65 20 74 68 65 20 72 61 6e   outside the ran
13d70 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ge.**           
13d80 6f 66 20 30 20 74 68 72 6f 75 67 68 20 4e 2d 31  of 0 through N-1
13d90 20 28 77 68 65 72 65 20 4e 20 69 73 20 74 68 65   (where N is the
13da0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
13db0 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  ).**           r
13dc0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
13dd0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
13de0 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  tring.**        
13df0 20 20 20 72 65 71 75 65 73 74 65 64 20 62 79 20     requested by 
13e00 74 68 65 20 66 6f 72 6d 61 74 20 73 70 65 63 69  the format speci
13e10 66 69 63 61 74 69 6f 6e 2e 0a 2a 2f 0a 63 68 61  fication..*/.cha
13e20 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
13e30 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
13e40 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
13e50 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
13e60 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
13e70 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
13e80 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
13e90 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
13ea0 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
13eb0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
13ec0 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
13ed0 74 65 6d 20 7b 48 31 37 33 30 30 7d 20 3c 53 32  tem {H17300} <S2
13ee0 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0000>.**.** The 
13ef0 53 51 4c 69 74 65 20 63 6f 72 65 20 20 75 73 65  SQLite core  use
13f00 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f  s these three ro
13f10 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f  utines for all o
13f20 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74  f its own.** int
13f30 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ernal memory all
13f40 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22  ocation needs. "
13f50 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65  Core" in the pre
13f60 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a  vious sentence.*
13f70 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  * does not inclu
13f80 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  de operating-sys
13f90 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53  tem specific VFS
13fa0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
13fb0 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73    The.** Windows
13fc0 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65   VFS uses native
13fd0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
13fe0 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70  ee() for some op
13ff0 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
14000 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
14010 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
14020 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
14030 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
14040 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
14050 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
14060 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
14070 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
14080 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
14090 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  c() is unable to
140a0 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65   obtain sufficie
140b0 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72  nt free.** memor
140c0 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20  y, it returns a 
140d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49  NULL pointer.  I
140e0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
140f0 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
14100 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
14110 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
14120 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
14130 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
14140 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
14150 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69  .** Calling sqli
14160 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
14170 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
14180 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
14190 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
141a0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
141b0 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
141c0 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
141d0 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
141e0 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 54  ht be reused.  T
141f0 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
14200 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
14210 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
14220 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
14230 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
14240 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
14250 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
14260 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
14270 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
14280 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
14290 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
142a0 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
142b0 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
142c0 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
142d0 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
142e0 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
142f0 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
14300 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
14310 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
14320 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
14330 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
14340 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
14350 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
14360 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
14370 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
14380 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
14390 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
143a0 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
143b0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
143c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
143d0 6f 72 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  or sqlite3_free(
143e0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
143f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69  ite3_realloc() i
14400 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
14410 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a  s to resize a.**
14420 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c   prior memory al
14430 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61  location to be a
14440 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c  t least N bytes,
14450 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
14460 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
14470 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79  ter.  The memory
14480 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62   allocation to b
14490 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65  e resized is the
144a0 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
144b0 74 65 72 2e 20 20 49 66 20 74 68 65 20 66 69 72  ter.  If the fir
144c0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
144d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
144e0 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
144f0 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
14500 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
14510 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
14520 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
14530 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73  oc(N) where N is
14540 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
14550 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
14560 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49  _realloc()..** I
14570 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  f the second par
14580 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
14590 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a  3_realloc() is z
145a0 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69  ero or.** negati
145b0 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
145c0 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20  vior is exactly 
145d0 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c  the same as call
145e0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  ing.** sqlite3_f
145f0 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69  ree(P) where P i
14600 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
14610 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
14620 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 73  _realloc()..** s
14630 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
14640 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
14650 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61  er to a memory a
14660 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
14670 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
14680 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c   in size or NULL
14690 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d   if sufficient m
146a0 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c  emory is unavail
146b0 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73  able..** If M is
146c0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
146d0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
146e0 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29  n, then min(N,M)
146f0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65   bytes.** of the
14700 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
14710 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74  n are copied int
14720 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
14730 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e  of buffer return
14740 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
14750 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74  _realloc() and t
14760 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
14770 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
14780 20 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   If sqlite3_real
14790 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55  loc() returns NU
147a0 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69  LL, then the pri
147b0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  or allocation.**
147c0 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a   is not freed..*
147d0 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20  *.** The memory 
147e0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
147f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  te3_malloc() and
14800 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
14810 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ().** is always 
14820 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65  aligned to at le
14830 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f  ast an 8 byte bo
14840 75 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a  undary. {END}.**
14850 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
14860 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
14870 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  f the memory all
14880 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
14890 6d 20 75 73 65 73 0a 2a 2a 20 74 68 65 20 6d 61  m uses.** the ma
148a0 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28  lloc(), realloc(
148b0 29 20 61 6e 64 20 66 72 65 65 28 29 20 70 72 6f  ) and free() pro
148c0 76 69 64 65 64 20 62 79 20 74 68 65 20 73 74 61  vided by the sta
148d0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
148e0 0a 2a 2a 20 7b 48 31 37 33 38 32 7d 20 48 6f 77  .** {H17382} How
148f0 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20  ever, if SQLite 
14900 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
14910 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d   the.** SQLITE_M
14920 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e  EMORY_SIZE=<i>NN
14930 4e 3c 2f 69 3e 20 43 20 70 72 65 70 72 6f 63 65  N</i> C preproce
14940 73 73 6f 72 20 6d 61 63 72 6f 20 28 77 68 65 72  ssor macro (wher
14950 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20  e <i>NNN</i>.** 
14960 69 73 20 61 6e 20 69 6e 74 65 67 65 72 29 2c 20  is an integer), 
14970 74 68 65 6e 20 53 51 4c 69 74 65 20 63 72 65 61  then SQLite crea
14980 74 65 20 61 20 73 74 61 74 69 63 20 61 72 72 61  te a static arra
14990 79 20 6f 66 20 61 74 20 6c 65 61 73 74 0a 2a 2a  y of at least.**
149a0 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65   <i>NNN</i> byte
149b0 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 20 75 73  s in size and us
149c0 65 73 20 74 68 61 74 20 61 72 72 61 79 20 66 6f  es that array fo
149d0 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e  r all of its dyn
149e0 61 6d 69 63 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  amic.** memory a
149f0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
14a00 20 7b 45 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e   {END}  Addition
14a10 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
14a20 74 6f 72 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 6d  tor options.** m
14a30 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
14a40 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
14a50 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20  **.** In SQLite 
14a60 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e  version 3.5.0 an
14a70 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20  d 3.5.1, it was 
14a80 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69  possible to defi
14a90 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45  ne.** the SQLITE
14aa0 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c  _OMIT_MEMORY_ALL
14ab0 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f  OCATION which wo
14ac0 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75  uld cause the bu
14ad0 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ilt-in.** implem
14ae0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73  entation of thes
14af0 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  e routines to be
14b00 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20   omitted.  That 
14b10 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
14b20 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69   no longer provi
14b30 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74  ded.  Only built
14b40 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
14b50 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65  ators can be use
14b60 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e  d..**.** The Win
14b70 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63  dows OS interfac
14b80 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a  e layer calls.**
14b90 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
14ba0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
14bb0 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
14bc0 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
14bd0 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
14be0 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
14bf0 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
14c00 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
14c10 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
14c20 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
14c30 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
14c40 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
14c50 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
14c60 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61  ocation errors a
14c70 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
14c80 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70  .** they are rep
14c90 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
14ca0 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
14cb0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
14cc0 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
14cd0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
14ce0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
14cf0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 33  S:.**.** {H17303
14d00 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
14d10 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72  malloc(N)] inter
14d20 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
14d30 68 65 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  her a pointer to
14d40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 20  .**           a 
14d50 6e 65 77 6c 79 20 63 68 65 63 6b 65 64 2d 6f 75  newly checked-ou
14d60 74 20 62 6c 6f 63 6b 20 6f 66 20 61 74 20 6c 65  t block of at le
14d70 61 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 6d  ast N bytes of m
14d80 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20  emory.**        
14d90 20 20 20 74 68 61 74 20 69 73 20 38 2d 62 79 74     that is 8-byt
14da0 65 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 69 74  e aligned, or it
14db0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66   returns NULL if
14dc0 20 69 74 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a   it is unable.**
14dd0 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 66 75             to fu
14de0 6c 66 69 6c 6c 20 74 68 65 20 72 65 71 75 65 73  lfill the reques
14df0 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 34  t..**.** {H17304
14e00 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
14e10 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72  malloc(N)] inter
14e20 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 4e  face returns a N
14e30 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 0a 2a  ULL pointer if.*
14e40 2a 20 20 20 20 20 20 20 20 20 20 20 4e 20 69 73  *           N is
14e50 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
14e60 75 61 6c 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a  ual to zero..**.
14e70 2a 2a 20 7b 48 31 37 33 30 35 7d 20 20 54 68 65  ** {H17305}  The
14e80 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50   [sqlite3_free(P
14e90 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 6c  )] interface rel
14ea0 65 61 73 65 73 20 6d 65 6d 6f 72 79 20 70 72 65  eases memory pre
14eb0 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20  viously.**      
14ec0 20 20 20 20 20 72 65 74 75 72 6e 65 64 20 66 72       returned fr
14ed0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
14ee0 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
14ef0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  3_realloc()],.**
14f00 20 20 20 20 20 20 20 20 20 20 20 6d 61 6b 69 6e             makin
14f10 67 20 69 74 20 61 76 61 69 6c 61 62 6c 65 20 66  g it available f
14f20 6f 72 20 72 65 75 73 65 2e 0a 2a 2a 0a 2a 2a 20  or reuse..**.** 
14f30 7b 48 31 37 33 30 36 7d 20 20 41 20 63 61 6c 6c  {H17306}  A call
14f40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
14f50 65 28 4e 55 4c 4c 29 5d 20 69 73 20 61 20 68 61  e(NULL)] is a ha
14f60 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
14f70 0a 2a 2a 20 7b 48 31 37 33 31 30 7d 20 20 41 20  .** {H17310}  A 
14f80 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
14f90 5f 72 65 61 6c 6c 6f 63 28 30 2c 4e 29 5d 20 69  _realloc(0,N)] i
14fa0 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
14fb0 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20  a call.**       
14fc0 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f      to [sqlite3_
14fd0 6d 61 6c 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a  malloc(N)]..**.*
14fe0 2a 20 7b 48 31 37 33 31 32 7d 20 20 41 20 63 61  * {H17312}  A ca
14ff0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
15000 65 61 6c 6c 6f 63 28 50 2c 30 29 5d 20 69 73 20  ealloc(P,0)] is 
15010 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20  equivalent to a 
15020 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  call.**         
15030 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72    to [sqlite3_fr
15040 65 65 28 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ee(P)]..**.** {H
15050 31 37 33 31 35 7d 20 20 54 68 65 20 53 51 4c 69  17315}  The SQLi
15060 74 65 20 63 6f 72 65 20 75 73 65 73 20 5b 73 71  te core uses [sq
15070 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
15080 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
15090 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  c()],.**        
150a0 20 20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f     and [sqlite3_
150b0 66 72 65 65 28 29 5d 20 66 6f 72 20 61 6c 6c 20  free()] for all 
150c0 6f 66 20 69 74 73 20 6d 65 6d 6f 72 79 20 61 6c  of its memory al
150d0 6c 6f 63 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  location and.** 
150e0 20 20 20 20 20 20 20 20 20 20 64 65 61 6c 6c 6f            deallo
150f0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
15100 0a 2a 2a 20 7b 48 31 37 33 31 38 7d 20 20 54 68  .** {H17318}  Th
15110 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  e [sqlite3_reall
15120 6f 63 28 50 2c 4e 29 5d 20 69 6e 74 65 72 66 61  oc(P,N)] interfa
15130 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
15140 72 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20  r a pointer.**  
15150 20 20 20 20 20 20 20 20 20 74 6f 20 61 20 62 6c           to a bl
15160 6f 63 6b 20 6f 66 20 63 68 65 63 6b 65 64 2d 6f  ock of checked-o
15170 75 74 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20  ut memory of at 
15180 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
15190 20 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20   size.**        
151a0 20 20 20 74 68 61 74 20 69 73 20 38 2d 62 79 74     that is 8-byt
151b0 65 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 61 20  e aligned, or a 
151c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
151d0 0a 2a 2a 20 7b 48 31 37 33 32 31 7d 20 20 57 68  .** {H17321}  Wh
151e0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  en [sqlite3_real
151f0 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e  loc(P,N)] return
15200 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
15210 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a  nter, it first.*
15220 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f 70 69  *           copi
15230 65 73 20 74 68 65 20 66 69 72 73 74 20 4b 20 62  es the first K b
15240 79 74 65 73 20 6f 66 20 63 6f 6e 74 65 6e 74 20  ytes of content 
15250 66 72 6f 6d 20 50 20 69 6e 74 6f 20 74 68 65 20  from P into the 
15260 6e 65 77 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  newly.**        
15270 20 20 20 61 6c 6c 6f 63 61 74 65 64 20 62 6c 6f     allocated blo
15280 63 6b 2c 20 77 68 65 72 65 20 4b 20 69 73 20 74  ck, where K is t
15290 68 65 20 6c 65 73 73 65 72 20 6f 66 20 4e 20 61  he lesser of N a
152a0 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a  nd the size of.*
152b0 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20  *           the 
152c0 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20  buffer P..**.** 
152d0 7b 48 31 37 33 32 32 7d 20 20 57 68 65 6e 20 5b  {H17322}  When [
152e0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
152f0 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20  P,N)] returns a 
15300 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
15310 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20  , it first.**   
15320 20 20 20 20 20 20 20 20 72 65 6c 65 61 73 65 73          releases
15330 20 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a   the buffer P..*
15340 2a 0a 2a 2a 20 7b 48 31 37 33 32 33 7d 20 20 57  *.** {H17323}  W
15350 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  hen [sqlite3_rea
15360 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72  lloc(P,N)] retur
15370 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 20 62 75 66  ns NULL, the buf
15380 66 65 72 20 50 20 69 73 0a 2a 2a 20 20 20 20 20  fer P is.**     
15390 20 20 20 20 20 20 6e 6f 74 20 6d 6f 64 69 66 69        not modifi
153a0 65 64 20 6f 72 20 72 65 6c 65 61 73 65 64 2e 0a  ed or released..
153b0 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e  **.** ASSUMPTION
153c0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35 30  S:.**.** {A17350
153d0 7d 20 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61  }  The pointer a
153e0 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c  rguments to [sql
153f0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64  ite3_free()] and
15400 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
15410 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  c()].**         
15420 20 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72    must be either
15430 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
15440 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
15450 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
15460 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f 63 61            invoca
15470 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
15480 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
15490 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
154a0 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 20  ] that have.**  
154b0 20 20 20 20 20 20 20 20 20 6e 6f 74 20 79 65 74           not yet
154c0 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a   been released..
154d0 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35 31 7d 20 20  **.** {A17351}  
154e0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
154f0 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
15500 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
15510 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  of.**           
15520 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
15530 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
15540 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
15550 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ng.**           
15560 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
15570 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
15580 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64  lloc()]..*/.void
15590 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
155a0 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  (int);.void *sql
155b0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
155c0 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  d*, int);.void s
155d0 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
155e0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
155f0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
15600 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
15610 20 7b 48 31 37 33 37 30 7d 20 3c 53 33 30 32 31   {H17370} <S3021
15620 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  0>.**.** SQLite 
15630 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74  provides these t
15640 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f  wo interfaces fo
15650 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74  r reporting on t
15660 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20  he status.** of 
15670 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  the [sqlite3_mal
15680 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
15690 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
156a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
156b0 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77  ].** routines, w
156c0 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75  hich form the bu
156d0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
156e0 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
156f0 65 6d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  em..**.** INVARI
15700 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  ANTS:.**.** {H17
15710 33 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  371} The [sqlite
15720 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
15730 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
15740 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
15750 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ytes.**         
15760 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
15770 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
15780 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
15790 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 0a 2a 2a  ot freed)..**.**
157a0 20 7b 48 31 37 33 37 33 7d 20 54 68 65 20 5b 73   {H17373} The [s
157b0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
157c0 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69  ghwater()] routi
157d0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d  ne returns the m
157e0 61 78 69 6d 75 6d 0a 2a 2a 20 20 20 20 20 20 20  aximum.**       
157f0 20 20 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c     value of [sql
15800 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
15810 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
15820 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
15830 20 20 20 20 20 20 20 20 20 20 77 61 73 20 6c 61            was la
15840 73 74 20 72 65 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  st reset..**.** 
15850 7b 48 31 37 33 37 34 7d 20 54 68 65 20 76 61 6c  {H17374} The val
15860 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
15870 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
15880 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20  used()] and.**  
15890 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
158a0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
158b0 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79  r()] include any
158c0 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 20 20 20   overhead.**    
158d0 20 20 20 20 20 20 61 64 64 65 64 20 62 79 20 53        added by S
158e0 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70  QLite in its imp
158f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
15900 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
15910 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  ],.**          b
15920 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
15930 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79  added by the any
15940 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74   underlying syst
15950 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 20 20  em library.**   
15960 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65 73 20         routines 
15970 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61  that [sqlite3_ma
15980 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c  lloc()] may call
15990 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 35 7d  ..**.** {H17375}
159a0 20 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68   The memory high
159b0 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
159c0 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
159d0 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
159e0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
159f0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
15a00 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
15a10 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  the parameter to
15a20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
15a30 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
15a40 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
15a50 65 2e 20 20 54 68 65 20 76 61 6c 75 65 20 72 65  e.  The value re
15a60 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20  turned.**       
15a70 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d     by [sqlite3_m
15a80 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
15a90 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
15aa0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20  water mark.**   
15ab0 20 20 20 20 20 20 20 70 72 69 6f 72 20 74 6f 20         prior to 
15ac0 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71  the reset..*/.sq
15ad0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
15ae0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
15af0 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69  void);.sqlite3_i
15b00 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
15b10 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
15b20 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
15b30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
15b40 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
15b50 62 65 72 20 47 65 6e 65 72 61 74 6f 72 20 7b 48  ber Generator {H
15b60 31 37 33 39 30 7d 20 3c 53 32 30 30 30 30 3e 0a  17390} <S20000>.
15b70 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e  **.** SQLite con
15b80 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61  tains a high-qua
15b90 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64  lity pseudo-rand
15ba0 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61  om number genera
15bb0 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20  tor (PRNG) used 
15bc0 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e  to.** select ran
15bd0 64 6f 6d 20 52 4f 57 49 44 73 20 77 68 65 6e 20  dom ROWIDs when 
15be0 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
15bf0 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
15c00 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
15c10 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
15c20 65 73 74 20 70 6f 73 73 69 62 6c 65 20 52 4f 57  est possible ROW
15c30 49 44 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  ID.  The PRNG is
15c40 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
15c50 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
15c60 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
15c70 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
15c80 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
15c90 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
15ca0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
15cb0 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
15cc0 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
15cd0 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
15ce0 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20   A call to this 
15cf0 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
15d00 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
15d10 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
15d20 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69   P..**.** The fi
15d30 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f  rst time this ro
15d40 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64  utine is invoked
15d50 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61   (either interna
15d60 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65  lly or by.** the
15d70 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68   application) th
15d80 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64  e PRNG is seeded
15d90 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
15da0 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  s obtained.** fr
15db0 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65  om the xRandomne
15dc0 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ss method of the
15dd0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
15de0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
15df0 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75  * On all subsequ
15e00 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c  ent invocations,
15e10 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
15e20 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
15e30 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
15e40 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
15e50 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
15e60 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
15e70 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
15e80 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
15e90 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  NTS:.**.** {H173
15ea0 39 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  92} The [sqlite3
15eb0 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 4e 2c 50 29  _randomness(N,P)
15ec0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 72 69 74  ] interface writ
15ed0 65 73 20 4e 20 62 79 74 65 73 20 6f 66 0a 2a 2a  es N bytes of.**
15ee0 20 20 20 20 20 20 20 20 20 20 68 69 67 68 2d 71            high-q
15ef0 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61  uality pseudo-ra
15f00 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
15f10 66 66 65 72 20 50 2e 0a 2a 2f 0a 76 6f 69 64 20  ffer P..*/.void 
15f20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
15f30 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
15f40 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
15f50 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
15f60 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
15f70 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 35 30  Callbacks {H1250
15f80 30 7d 20 3c 53 37 30 31 30 30 3e 0a 2a 2a 0a 2a  0} <S70100>.**.*
15f90 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
15fa0 65 67 69 73 74 65 72 73 20 61 20 61 75 74 68 6f  egisters a autho
15fb0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
15fc0 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
15fd0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
15fe0 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
15ff0 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
16000 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
16010 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
16020 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
16030 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
16040 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
16050 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
16060 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
16070 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
16080 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
16090 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
160a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
160b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
160c0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
160d0 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
160e0 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
160f0 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
16100 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
16110 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
16120 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
16130 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
16140 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
16150 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
16160 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
16170 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
16180 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61 75  allowed.  The au
16190 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
161a0 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
161b0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
161c0 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
161d0 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
161e0 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
161f0 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
16200 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
16210 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
16220 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
16230 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
16240 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
16250 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
16260 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
16270 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
16280 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
16290 72 72 6f 72 2e 20 20 49 66 20 74 68 65 20 61 75  rror.  If the au
162a0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
162b0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
162c0 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
162d0 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
162e0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
162f0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
16300 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
16310 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
16320 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
16330 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
16340 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
16350 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
16360 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
16370 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
16380 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
16390 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
163a0 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
163b0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
163c0 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
163d0 6b 2e 20 20 57 68 65 6e 20 74 68 65 20 63 61 6c  k.  When the cal
163e0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
163f0 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
16400 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
16410 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
16420 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
16430 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
16440 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
16450 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
16460 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
16470 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
16480 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
16490 65 64 2e 20 20 49 66 20 74 68 65 20 61 75 74 68  ed.  If the auth
164a0 6f 72 69 7a 65 72 20 63 6f 64 65 20 69 73 20 5b  orizer code is [
164b0 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
164c0 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
164d0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
164e0 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
164f0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
16500 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
16510 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
16520 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
16530 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
16540 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
16550 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
16560 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
16570 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
16580 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
16590 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
165a0 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
165b0 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
165c0 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
165d0 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
165e0 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
165f0 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
16600 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
16610 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
16620 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
16630 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
16640 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
16650 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
16660 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
16670 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
16680 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
16690 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  . The second par
166a0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
166b0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
166c0 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f  integer [SQLITE_
166d0 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f  COPY | action co
166e0 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
166f0 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63  es.** the partic
16700 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62  ular action to b
16710 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 54 68  e authorized. Th
16720 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
16730 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
16740 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
16750 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
16760 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
16770 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
16780 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
16790 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
167a0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
167b0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  ized..**.** An a
167c0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65  uthorizer is use
167d0 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
167e0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
167f0 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ing].** SQL stat
16800 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75  ements from an u
16810 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c  ntrusted source,
16820 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20   to ensure that 
16830 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
16840 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79  ts.** do not try
16850 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20   to access data 
16860 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c  they are not all
16870 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20  owed to see, or 
16880 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
16890 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75  .** try to execu
168a0 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61  te malicious sta
168b0 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d  tements that dam
168c0 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  age the database
168d0 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
168e0 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
168f0 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73  n may allow a us
16900 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69  er to enter arbi
16910 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65  trary.** SQL que
16920 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74  ries for evaluat
16930 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73  ion by a databas
16940 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c  e.  But the appl
16950 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20  ication does.** 
16960 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65  not want the use
16970 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20  r to be able to 
16980 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63  make arbitrary c
16990 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a  hanges to the.**
169a0 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61   database.  An a
169b0 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20  uthorizer could 
169c0 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70  then be put in p
169d0 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a  lace while the.*
169e0 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  * user-entered S
169f0 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c  QL is being [sql
16a00 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
16a10 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a  repared] that.**
16a20 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79   disallows every
16a30 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45  thing except [SE
16a40 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73  LECT] statements
16a50 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ..**.** Applicat
16a60 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74  ions that need t
16a70 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72  o process SQL fr
16a80 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  om untrusted sou
16a90 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c  rces.** might al
16aa0 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65  so consider lowe
16ab0 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69  ring resource li
16ac0 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69  mits using [sqli
16ad0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
16ae0 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74  and limiting dat
16af0 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67  abase size using
16b00 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63   the [max_page_c
16b10 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a  ount] [PRAGMA].*
16b20 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  * in addition to
16b30 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72   using an author
16b40 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79  izer..**.** Only
16b50 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
16b60 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
16b70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
16b80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
16b90 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
16ba0 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
16bb0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
16bc0 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
16bd0 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
16be0 20 20 44 69 73 61 62 6c 65 20 74 68 65 20 61 75    Disable the au
16bf0 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
16c00 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
16c10 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
16c20 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
16c30 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
16c40 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
16c50 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
16c60 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
16c70 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
16c80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
16c90 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
16ca0 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
16cb0 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
16cc0 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
16cd0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
16ce0 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
16cf0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
16d00 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
16d10 2a 0a 2a 2a 20 7b 48 31 32 35 30 31 7d 20 54 68  *.** {H12501} Th
16d20 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
16d30 75 74 68 6f 72 69 7a 65 72 28 44 2c 2e 2e 2e 29  uthorizer(D,...)
16d40 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
16d50 73 74 65 72 73 20 61 0a 2a 2a 20 20 20 20 20 20  sters a.**      
16d60 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72 20 63      authorizer c
16d70 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 64 61 74  allback with dat
16d80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16d90 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30   D..**.** {H1250
16da0 32 7d 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  2} The authorize
16db0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
16dc0 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
16dd0 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 20  tements are.**  
16de0 20 20 20 20 20 20 20 20 62 65 69 6e 67 20 63 6f          being co
16df0 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  mpiled..**.** {H
16e00 31 32 35 30 33 7d 20 49 66 20 74 68 65 20 61 75  12503} If the au
16e10 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
16e20 6b 20 72 65 74 75 72 6e 73 20 61 6e 79 20 76 61  k returns any va
16e30 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a  lue other than.*
16e40 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
16e50 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
16e60 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
16e70 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 6e 0a  ITE_DENY], then.
16e80 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
16e90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
16ea0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
16eb0 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 63  lent call that c
16ec0 61 75 73 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  aused.**        
16ed0 20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72    the authorizer
16ee0 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e   callback to run
16ef0 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68   shall fail with
16f00 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
16f10 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65  [SQLITE_ERROR] e
16f20 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e  rror code and an
16f30 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72   appropriate err
16f40 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
16f50 2a 20 7b 48 31 32 35 30 34 7d 20 57 68 65 6e 20  * {H12504} When 
16f60 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
16f70 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
16f80 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65  [SQLITE_OK], the
16f90 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 20   operation.**   
16fa0 20 20 20 20 20 20 20 64 65 73 63 72 69 62 65 64         described
16fb0 20 69 73 20 70 72 6f 63 65 73 73 65 64 20 6e 6f   is processed no
16fc0 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48  rmally..**.** {H
16fd0 31 32 35 30 35 7d 20 57 68 65 6e 20 74 68 65 20  12505} When the 
16fe0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
16ff0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
17000 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
17010 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
17020 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
17030 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
17040 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64  call that caused
17050 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
17060 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17070 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c  back to run shal
17080 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20  l fail.**       
17090 20 20 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49     with an [SQLI
170a0 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20  TE_ERROR] error 
170b0 63 6f 64 65 20 61 6e 64 20 61 6e 20 65 72 72 6f  code and an erro
170c0 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20  r message.**    
170d0 20 20 20 20 20 20 65 78 70 6c 61 69 6e 69 6e 67        explaining
170e0 20 74 68 61 74 20 61 63 63 65 73 73 20 69 73 20   that access is 
170f0 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  denied..**.** {H
17100 31 32 35 30 36 7d 20 49 66 20 74 68 65 20 61 75  12506} If the au
17110 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74  thorizer code (t
17120 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
17130 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
17140 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  er.**          c
17150 61 6c 6c 62 61 63 6b 29 20 69 73 20 5b 53 51 4c  allback) is [SQL
17160 49 54 45 5f 52 45 41 44 5d 20 61 6e 64 20 74 68  ITE_READ] and th
17170 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
17180 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
17190 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
171a0 45 5f 49 47 4e 4f 52 45 5d 2c 20 74 68 65 6e 20  E_IGNORE], then 
171b0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
171c0 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
171d0 75 63 74 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  ucted to.**     
171e0 20 20 20 20 20 69 6e 73 65 72 74 20 61 20 4e 55       insert a NU
171f0 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
17200 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
17210 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
17220 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20   have.**        
17230 20 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b    been read if [
17240 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
17250 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  een returned..**
17260 0a 2a 2a 20 7b 48 31 32 35 30 37 7d 20 49 66 20  .** {H12507} If 
17270 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
17280 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72  ode (the 2nd par
17290 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
172a0 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20  thorizer.**     
172b0 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69       callback) i
172c0 73 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72  s anything other
172d0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45   than [SQLITE_RE
172e0 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  AD], then.**    
172f0 20 20 20 20 20 20 61 20 72 65 74 75 72 6e 20 6f        a return o
17300 66 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  f [SQLITE_IGNORE
17310 5d 20 68 61 73 20 74 68 65 20 73 61 6d 65 20 65  ] has the same e
17320 66 66 65 63 74 20 61 73 20 5b 53 51 4c 49 54 45  ffect as [SQLITE
17330 5f 44 45 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  _DENY]..**.** {H
17340 31 32 35 31 30 7d 20 54 68 65 20 66 69 72 73 74  12510} The first
17350 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
17360 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
17370 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
17380 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
17390 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
173a0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
173b0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
173c0 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  r()] interface..
173d0 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 31 7d 20 54  **.** {H12511} T
173e0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
173f0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
17400 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
17410 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  r.**          [S
17420 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
17430 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
17440 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61 72  pecifies the par
17450 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a  ticular action.*
17460 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 62 65  *          to be
17470 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
17480 2a 2a 20 7b 48 31 32 35 31 32 7d 20 54 68 65 20  ** {H12512} The 
17490 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
174a0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  xth parameters t
174b0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
174c0 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  re.**          z
174d0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
174e0 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
174f0 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ain.**          
17500 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69  additional detai
17510 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
17520 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
17530 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ized..**.** {H12
17540 35 32 30 7d 20 45 61 63 68 20 63 61 6c 6c 20 74  520} Each call t
17550 6f 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  o [sqlite3_set_a
17560 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 6f 76 65  uthorizer()] ove
17570 72 72 69 64 65 73 0a 2a 2a 20 20 20 20 20 20 20  rrides.**       
17580 20 20 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c     any previousl
17590 79 20 69 6e 73 74 61 6c 6c 65 64 20 61 75 74 68  y installed auth
175a0 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  orizer..**.** {H
175b0 31 32 35 32 31 7d 20 41 20 4e 55 4c 4c 20 61 75  12521} A NULL au
175c0 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20 74  thorizer means t
175d0 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61  hat no authoriza
175e0 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
175f0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
17600 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  oked..**.** {H12
17610 35 32 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74  522} The default
17620 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e   authorizer is N
17630 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
17640 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
17650 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
17660 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
17670 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
17680 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
17690 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
176a0 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
176b0 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
176c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
176d0 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
176e0 72 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 39 30  rn Codes {H12590
176f0 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a  } <H12500>.**.**
17700 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
17710 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
17720 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
17730 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
17740 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
17750 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
17760 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
17770 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
17780 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
17790 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
177a0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
177b0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
177c0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
177d0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
177e0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
177f0 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
17800 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
17810 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
17820 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
17830 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
17840 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
17850 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
17860 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
17870 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
17880 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
17890 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
178a0 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
178b0 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
178c0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
178d0 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
178e0 65 73 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 32  es {H12550} <H12
178f0 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  500>.**.** The [
17900 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
17910 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
17920 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
17930 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
17940 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
17950 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
17960 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
17970 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
17980 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
17990 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
179a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
179b0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
179c0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
179d0 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
179e0 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
179f0 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
17a00 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
17a10 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
17a20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
17a30 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
17a40 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
17a50 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
17a60 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
17a70 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
17a80 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
17a90 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
17aa0 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
17ab0 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
17ac0 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
17ad0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
17ae0 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
17af0 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
17b00 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
17b10 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
17b20 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
17b30 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
17b40 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   The 5th paramet
17b50 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
17b60 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17b70 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
17b80 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
17b90 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
17ba0 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
17bb0 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70  able.  The 6th p
17bc0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
17bd0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
17be0 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
17bf0 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
17c00 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
17c10 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
17c20 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
17c30 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
17c40 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
17c50 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
17c60 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
17c70 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  om.** top-level 
17c80 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20  SQL code..**.** 
17c90 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
17ca0 2a 20 7b 48 31 32 35 35 31 7d 20 54 68 65 20 73  * {H12551} The s
17cb0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
17cc0 74 6f 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  to an.**        
17cd0 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61    [sqlite3_set_a
17ce0 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
17cf0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d  orizer callback]
17d00 20 69 73 20 61 6c 77 61 79 73 20 61 6e 20 69 6e   is always an in
17d10 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  teger.**        
17d20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c    [SQLITE_COPY |
17d30 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65   authorizer code
17d40 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
17d50 20 77 68 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20   what action.** 
17d60 20 20 20 20 20 20 20 20 20 69 73 20 62 65 69 6e           is bein
17d70 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  g authorized..**
17d80 0a 2a 2a 20 7b 48 31 32 35 35 32 7d 20 54 68 65  .** {H12552} The
17d90 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72   3rd and 4th par
17da0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 0a 2a  ameters to the.*
17db0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
17dc0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
17dd0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 61 74 69  er | authorizati
17de0 6f 6e 20 63 61 6c 6c 62 61 63 6b 5d 0a 2a 2a 20  on callback].** 
17df0 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 62 65           will be
17e00 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
17e10 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
17e20 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20 20 20   which.**       
17e30 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20     [SQLITE_COPY 
17e40 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64  | authorizer cod
17e50 65 5d 20 69 73 20 75 73 65 64 20 61 73 20 74 68  e] is used as th
17e60 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17e70 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35  er..**.** {H1255
17e80 33 7d 20 54 68 65 20 35 74 68 20 70 61 72 61 6d  3} The 5th param
17e90 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20  eter to the.**  
17ea0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
17eb0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
17ec0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
17ed0 6c 62 61 63 6b 5d 20 69 73 20 74 68 65 20 6e 61  lback] is the na
17ee0 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  me.**          o
17ef0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
17f00 65 78 61 6d 70 6c 65 3a 20 22 6d 61 69 6e 22 2c  example: "main",
17f10 20 22 74 65 6d 70 22 2c 20 65 74 63 2e 29 20 69   "temp", etc.) i
17f20 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 0a 2a 2a  f applicable..**
17f30 0a 2a 2a 20 7b 48 31 32 35 35 34 7d 20 54 68 65  .** {H12554} The
17f40 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
17f50 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
17f60 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61    [sqlite3_set_a
17f70 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
17f80 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d  orizer callback]
17f90 20 69 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20   is the name.** 
17fa0 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
17fb0 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
17fc0 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
17fd0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
17fe0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  or.**          t
17ff0 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
18000 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
18010 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
18020 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
18030 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  m.**          to
18040 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65  p-level SQL code
18050 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ..*/./**********
18060 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18070 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18080 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 3rd **********
18090 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 4th *********
180a0 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  **/.#define SQLI
180b0 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20  TE_CREATE_INDEX 
180c0 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20           1   /* 
180d0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
180e0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
180f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18100 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20  E_CREATE_TABLE  
18110 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54          2   /* T
18120 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
18130 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18140 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18150 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44  _CREATE_TEMP_IND
18160 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e  EX     3   /* In
18170 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
18180 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
18190 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
181a0 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c  CREATE_TEMP_TABL
181b0 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62  E     4   /* Tab
181c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
181d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
181e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
181f0 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47  REATE_TEMP_TRIGG
18200 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67  ER   5   /* Trig
18210 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
18220 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
18230 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
18240 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20  EATE_TEMP_VIEW  
18250 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20      6   /* View 
18260 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
18270 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18280 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
18290 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  ATE_TRIGGER     
182a0 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65     7   /* Trigge
182b0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
182c0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
182d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
182e0 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  TE_VIEW         
182f0 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    8   /* View Na
18300 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
18310 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
18320 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54  ine SQLITE_DELET
18330 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
18340 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   9   /* Table Na
18350 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
18360 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18370 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49  ne SQLITE_DROP_I
18380 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31  NDEX           1
18390 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  0   /* Index Nam
183a0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
183b0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
183c0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41  e SQLITE_DROP_TA
183d0 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31  BLE           11
183e0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
183f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
18400 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18410 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
18420 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20  P_INDEX      12 
18430 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
18440 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
18450 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18460 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
18470 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20  _TABLE      13  
18480 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
18490 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
184a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
184b0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
184c0 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20  TRIGGER    14   
184d0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
184e0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
184f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18500 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56  LITE_DROP_TEMP_V
18510 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f  IEW       15   /
18520 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
18530 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18540 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18550 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52  ITE_DROP_TRIGGER
18560 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a           16   /*
18570 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
18580 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18590 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
185a0 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20  TE_DROP_VIEW    
185b0 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20          17   /* 
185c0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
185d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
185e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
185f0 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20  E_INSERT        
18600 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54         18   /* T
18610 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
18620 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18630 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18640 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
18650 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72        19   /* Pr
18660 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73  agma Name     1s
18670 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f  t arg or NULL */
18680 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18690 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
186a0 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62       20   /* Tab
186b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
186c0 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
186d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
186e0 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
186f0 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c      21   /* NULL
18700 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
18710 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
18720 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
18730 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20  ANSACTION       
18740 20 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20     22   /* NULL 
18750 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
18760 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18770 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44  efine SQLITE_UPD
18780 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
18790 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    23   /* Table 
187a0 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
187b0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
187c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41  fine SQLITE_ATTA
187d0 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
187e0 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d   24   /* Filenam
187f0 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  e        NULL   
18800 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
18810 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43  ine SQLITE_DETAC
18820 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
18830 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  25   /* Database
18840 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
18850 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18860 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f  ne SQLITE_ALTER_
18870 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
18880 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
18890 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d  Name   Table Nam
188a0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
188b0 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58  e SQLITE_REINDEX
188c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37                27
188d0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
188e0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
188f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18900 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20   SQLITE_ANALYZE 
18910 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20               28 
18920 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
18930 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18940 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18950 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54  SQLITE_CREATE_VT
18960 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20  ABLE        29  
18970 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
18980 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
18990 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
189a0 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c  QLITE_DROP_VTABL
189b0 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20  E          30   
189c0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
189d0 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
189e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
189f0 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20  LITE_FUNCTION   
18a00 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f            31   /
18a10 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20  * Function Name 
18a20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18a30 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18a40 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
18a50 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
18a60 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
18a70 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
18a80 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
18a90 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
18aa0 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c 53 36  ons {H12280} <S6
18ab0 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0400>.**.** Thes
18ac0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
18ad0 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
18ae0 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
18af0 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
18b00 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
18b10 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
18b20 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
18b30 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ents..**.** The 
18b40 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
18b50 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
18b60 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
18b70 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
18b80 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
18b90 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
18ba0 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
18bb0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
18bc0 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61  ep()]..** The ca
18bd0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61  llback returns a
18be0 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
18bf0 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   of the SQL stat
18c00 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73  ement text.** as
18c10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
18c20 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
18c30 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  uting.  Addition
18c40 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63  al callbacks occ
18c50 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
18c60 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
18c70 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
18c80 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
18c90 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
18ca0 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
18cb0 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
18cc0 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
18cd0 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  igger..**.** The
18ce0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
18cf0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
18d00 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
18d10 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
18d20 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
18d30 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
18d40 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61    The profile ca
18d50 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
18d60 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
18d70 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
18d80 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
18d90 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
18da0 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
18db0 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
18dc0 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a  took to run..**.
18dd0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
18de0 72 6f 66 69 6c 65 28 29 20 41 50 49 20 69 73 20  rofile() API is 
18df0 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64  currently consid
18e00 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61  ered experimenta
18e10 6c 20 61 6e 64 0a 2a 2a 20 69 73 20 73 75 62 6a  l and.** is subj
18e20 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72  ect to change or
18e30 20 72 65 6d 6f 76 61 6c 20 69 6e 20 61 20 66 75   removal in a fu
18e40 74 75 72 65 20 72 65 6c 65 61 73 65 2e 0a 2a 2a  ture release..**
18e50 0a 2a 2a 20 54 68 65 20 74 72 69 67 67 65 72 20  .** The trigger 
18e60 72 65 70 6f 72 74 69 6e 67 20 66 65 61 74 75 72  reporting featur
18e70 65 20 6f 66 20 74 68 65 20 74 72 61 63 65 20 63  e of the trace c
18e80 61 6c 6c 62 61 63 6b 20 69 73 20 63 6f 6e 73 69  allback is consi
18e90 64 65 72 65 64 0a 2a 2a 20 65 78 70 65 72 69 6d  dered.** experim
18ea0 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62  ental and is sub
18eb0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f  ject to change o
18ec0 72 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74  r removal in fut
18ed0 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  ure releases..**
18ee0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
18ef0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
18f00 20 61 6c 73 6f 20 61 64 64 20 6e 65 77 20 74 72   also add new tr
18f10 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ace callback.** 
18f20 69 6e 76 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 0a  invocations..**.
18f30 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
18f40 2a 0a 2a 2a 20 7b 48 31 32 32 38 31 7d 20 54 68  *.** {H12281} Th
18f50 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
18f60 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
18f70 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  y [sqlite3_trace
18f80 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ()] is.**       
18f90 20 20 20 77 68 65 6e 65 76 65 72 20 61 6e 20 53     whenever an S
18fa0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  QL statement fir
18fb0 73 74 20 62 65 67 69 6e 73 20 74 6f 20 65 78 65  st begins to exe
18fc0 63 75 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20  cute and.**     
18fd0 20 20 20 20 20 77 68 65 6e 65 76 65 72 20 61 20       whenever a 
18fe0 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72  trigger subprogr
18ff0 61 6d 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  am first begins 
19000 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48  to run..**.** {H
19010 31 32 32 38 32 7d 20 45 61 63 68 20 63 61 6c 6c  12282} Each call
19020 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   to [sqlite3_tra
19030 63 65 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20  ce()] overrides 
19040 74 68 65 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a  the previously.*
19050 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73  *          regis
19060 74 65 72 65 64 20 74 72 61 63 65 20 63 61 6c 6c  tered trace call
19070 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  back..**.** {H12
19080 32 38 33 7d 20 41 20 4e 55 4c 4c 20 74 72 61 63  283} A NULL trac
19090 65 20 63 61 6c 6c 62 61 63 6b 20 64 69 73 61 62  e callback disab
190a0 6c 65 73 20 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a  les tracing..**.
190b0 2a 2a 20 7b 48 31 32 32 38 34 7d 20 54 68 65 20  ** {H12284} The 
190c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
190d0 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c  o the trace call
190e0 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
190f0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  f.**          th
19100 65 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  e pointer which 
19110 77 61 73 20 74 68 65 20 33 72 64 20 61 72 67 75  was the 3rd argu
19120 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
19130 5f 74 72 61 63 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _trace()]..**.**
19140 20 7b 48 31 32 32 38 35 7d 20 54 68 65 20 73 65   {H12285} The se
19150 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
19160 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62   the trace callb
19170 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20 20  ack is a.**     
19180 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
19190 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
191a0 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
191b0 20 6f 72 69 67 69 6e 61 6c 20 74 65 78 74 0a 2a   original text.*
191c0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
191d0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
191e0 61 73 20 69 74 20 77 61 73 20 70 61 73 73 65 64  as it was passed
191f0 20 69 6e 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70   into [sqlite3_p
19200 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20  repare_v2()].** 
19210 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
19220 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20 61  equivalent, or a
19230 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 69 6e  n SQL comment in
19240 64 69 63 61 74 69 6e 67 20 74 68 65 20 62 65 67  dicating the beg
19250 69 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  inning.**       
19260 20 20 20 6f 66 20 61 20 74 72 69 67 67 65 72 20     of a trigger 
19270 73 75 62 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  subprogram..**.*
19280 2a 20 7b 48 31 32 32 38 37 7d 20 54 68 65 20 63  * {H12287} The c
19290 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
192a0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b   registered by [
192b0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
192c0 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  )] is invoked.**
192d0 20 20 20 20 20 20 20 20 20 20 61 73 20 65 61 63            as eac
192e0 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
192f0 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20  finishes..**.** 
19300 7b 48 31 32 32 38 38 7d 20 54 68 65 20 66 69 72  {H12288} The fir
19310 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
19320 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  the profile call
19330 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
19340 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  f.**          th
19350 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
19360 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66  to [sqlite3_prof
19370 69 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ile()]..**.** {H
19380 31 32 32 38 39 7d 20 54 68 65 20 73 65 63 6f 6e  12289} The secon
19390 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
193a0 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
193b0 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20 20  ack is a.**     
193c0 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
193d0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
193e0 67 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20  g that contains 
193f0 74 68 65 20 63 6f 6d 70 6c 65 74 65 20 74 65 78  the complete tex
19400 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  t of.**         
19410 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
19420 6e 74 20 61 73 20 69 74 20 77 61 73 20 70 72 6f  nt as it was pro
19430 63 65 73 73 65 64 20 62 79 20 5b 73 71 6c 69 74  cessed by [sqlit
19440 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
19450 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
19460 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2e 0a  the equivalent..
19470 2a 2a 0a 2a 2a 20 7b 48 31 32 32 39 30 7d 20 54  **.** {H12290} T
19480 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
19490 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c  er to the profil
194a0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
194b0 20 65 73 74 69 6d 61 74 65 0a 2a 2a 20 20 20 20   estimate.**    
194c0 20 20 20 20 20 20 6f 66 20 74 68 65 20 6e 75 6d        of the num
194d0 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  ber of nanosecon
194e0 64 73 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b  ds of wall-clock
194f0 20 74 69 6d 65 20 72 65 71 75 69 72 65 64 20 74   time required t
19500 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 75  o.**          ru
19510 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
19520 65 6e 74 20 66 72 6f 6d 20 73 74 61 72 74 20 74  ent from start t
19530 6f 20 66 69 6e 69 73 68 2e 0a 2a 2f 0a 76 6f 69  o finish..*/.voi
19540 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
19550 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
19560 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
19570 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
19580 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  d*);.void *sqlit
19590 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
195a0 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
195b0 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
195c0 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
195d0 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
195e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
195f0 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
19600 73 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31  ss Callbacks {H1
19610 32 39 31 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a  2910} <S60400>.*
19620 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
19630 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63  e configures a c
19640 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
19650 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65   - the.** progre
19660 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68  ss callback - th
19670 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65  at is invoked pe
19680 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
19690 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e  g long.** runnin
196a0 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  g calls to [sqli
196b0 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
196c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
196d0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  d.** [sqlite3_ge
196e0 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20  t_table()].  An 
196f0 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
19700 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
19710 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
19720 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
19730 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
19740 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70 72  .**.** If the pr
19750 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
19760 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
19770 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  , the operation 
19780 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65  is.** interrupte
19790 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65  d.  This feature
197a0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
197b0 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22  implement a.** "
197c0 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
197d0 6e 20 61 20 47 55 49 20 64 69 61 6c 6f 67 20 62  n a GUI dialog b
197e0 6f 78 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ox..**.** INVARI
197f0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
19800 39 31 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63  911} The callbac
19810 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
19820 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
19830 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
19840 72 28 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r().**          
19850 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  is invoked perio
19860 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
19870 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
19880 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  s to.**         
19890 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
198a0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 32  ]..**.** {H12912
198b0 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 63  } The progress c
198c0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
198d0 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 76 65 72  ed once for ever
198e0 79 20 4e 20 76 69 72 74 75 61 6c 0a 2a 2a 20 20  y N virtual.**  
198f0 20 20 20 20 20 20 20 20 6d 61 63 68 69 6e 65 20          machine 
19900 6f 70 63 6f 64 65 73 2c 20 77 68 65 72 65 20 4e  opcodes, where N
19910 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   is the second a
19920 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20  rgument to.**   
19930 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69         the [sqli
19940 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
19950 64 6c 65 72 28 29 5d 20 63 61 6c 6c 20 74 68 61  dler()] call tha
19960 74 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20  t registered.** 
19970 20 20 20 20 20 20 20 20 20 74 68 65 20 63 61 6c           the cal
19980 6c 62 61 63 6b 2e 20 20 49 66 20 4e 20 69 73 20  lback.  If N is 
19990 6c 65 73 73 20 74 68 61 6e 20 31 2c 20 73 71 6c  less than 1, sql
199a0 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
199b0 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20 20  ndler().**      
199c0 20 20 20 20 61 63 74 73 20 61 73 20 69 66 20 61      acts as if a
199d0 20 4e 55 4c 4c 20 70 72 6f 67 72 65 73 73 20 68   NULL progress h
199e0 61 6e 64 6c 65 72 20 68 61 64 20 62 65 65 6e 20  andler had been 
199f0 73 70 65 63 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a  specified..**.**
19a00 20 7b 48 31 32 39 31 33 7d 20 54 68 65 20 70 72   {H12913} The pr
19a10 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
19a20 69 74 73 65 6c 66 20 69 73 20 69 64 65 6e 74 69  itself is identi
19a30 66 69 65 64 20 62 79 20 74 68 65 20 74 68 69 72  fied by the thir
19a40 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  d.**          ar
19a50 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
19a60 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
19a70 65 72 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  er()..**.** {H12
19a80 39 31 34 7d 20 54 68 65 20 66 6f 75 72 74 68 20  914} The fourth 
19a90 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
19aa0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
19ab0 64 6c 65 72 28 29 20 69 73 20 61 0a 2a 2a 20 20  dler() is a.**  
19ac0 20 20 20 20 20 20 20 20 76 6f 69 64 20 70 6f 69          void poi
19ad0 6e 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74  nter passed to t
19ae0 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
19af0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
19b00 20 66 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 74   function each t
19b10 69 6d 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  ime it is invoke
19b20 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 35  d..**.** {H12915
19b30 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b  } If a call to [
19b40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
19b50 72 65 73 75 6c 74 73 20 69 6e 20 66 65 77 65 72  results in fewer
19b60 20 74 68 61 6e 20 4e 20 6f 70 63 6f 64 65 73 0a   than N opcodes.
19b70 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 69 6e  **          bein
19b80 67 20 65 78 65 63 75 74 65 64 2c 20 74 68 65 6e  g executed, then
19b90 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
19ba0 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76 65 72 20  llback is never 
19bb0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  invoked..**.** {
19bc0 48 31 32 39 31 36 7d 20 45 76 65 72 79 20 63 61  H12916} Every ca
19bd0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ll to [sqlite3_p
19be0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
19bf0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
19c00 76 65 72 77 72 69 74 65 73 20 61 6e 79 20 70 72  verwrites any pr
19c10 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
19c20 72 65 64 20 70 72 6f 67 72 65 73 73 20 68 61 6e  red progress han
19c30 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  dler..**.** {H12
19c40 39 31 37 7d 20 49 66 20 74 68 65 20 70 72 6f 67  917} If the prog
19c50 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
19c60 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 20 74 68  lback is NULL th
19c70 65 6e 20 6e 6f 20 70 72 6f 67 72 65 73 73 0a 2a  en no progress.*
19c80 2a 20 20 20 20 20 20 20 20 20 20 68 61 6e 64 6c  *          handl
19c90 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  er is invoked..*
19ca0 2a 0a 2a 2a 20 7b 48 31 32 39 31 38 7d 20 49 66  *.** {H12918} If
19cb0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
19cc0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61  llback returns a
19cd0 20 72 65 73 75 6c 74 20 6f 74 68 65 72 20 74 68   result other th
19ce0 61 6e 20 30 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  an 0, then.**   
19cf0 20 20 20 20 20 20 20 74 68 65 20 62 65 68 61 76         the behav
19d00 69 6f 72 20 69 73 20 61 20 69 66 20 5b 73 71 6c  ior is a if [sql
19d10 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
19d20 5d 20 68 61 64 20 62 65 65 6e 20 63 61 6c 6c 65  ] had been calle
19d30 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c  d..**          <
19d40 53 33 30 35 30 30 3e 0a 2a 2f 0a 76 6f 69 64 20  S30500>.*/.void 
19d50 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
19d60 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
19d70 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
19d80 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
19d90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19da0 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
19db0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
19dc0 6e 20 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 32  n {H12700} <S402
19dd0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
19de0 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
19df0 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
19e00 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65   file whose name
19e10 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65   is given by the
19e20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
19e30 75 6d 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e  ument. The filen
19e40 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
19e50 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
19e60 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
19e70 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
19e80 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
19e90 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
19ea0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
19eb0 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
19ec0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
19ed0 20 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   A [database con
19ee0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
19ef0 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65  is usually.** re
19f00 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
19f10 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f   even if an erro
19f20 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
19f30 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
19f40 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69   that.** if SQLi
19f50 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
19f60 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
19f70 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
19f80 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a  ite3] object,.**
19f90 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20   a NULL will be 
19fa0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
19fb0 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
19fc0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
19fd0 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65  sqlite3].** obje
19fe0 63 74 2e 20 49 66 20 74 68 65 20 64 61 74 61 62  ct. If the datab
19ff0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61  ase is opened (a
1a000 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73  nd/or created) s
1a010 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65  uccessfully, the
1a020 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  n.** [SQLITE_OK]
1a030 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
1a040 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
1a050 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
1a060 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  rned.  The.** [s
1a070 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1a080 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
1a090 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  msg16()] routine
1a0a0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
1a0b0 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
1a0c0 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
1a0d0 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
1a0e0 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  e error..**.** T
1a0f0 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
1a100 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61  ing for the data
1a110 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46  base will be UTF
1a120 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33  -8 if.** sqlite3
1a130 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
1a140 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1a150 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54  called and.** UT
1a160 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
1a170 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66  ve byte order if
1a180 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1a190 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  ) is used..**.**
1a1a0 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   Whether or not 
1a1b0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
1a1c0 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65  when it is opene
1a1d0 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20  d, resources.** 
1a1e0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1a1f0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
1a200 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
1a210 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61   should be relea
1a220 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e  sed by.** passin
1a230 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
1a240 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69  _close()] when i
1a250 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
1a260 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
1a270 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  he sqlite3_open_
1a280 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
1a290 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
1a2a0 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65  3_open().** exce
1a2b0 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70  pt that it accep
1a2c0 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  ts two additiona
1a2d0 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72  l parameters for
1a2e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74   additional cont
1a2f0 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  rol.** over the 
1a300 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
1a310 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c  nection.  The fl
1a320 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 63 61  ags parameter ca
1a330 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
1a340 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
1a350 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
1a360 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
1a370 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
1a380 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
1a390 45 58 5d 20 66 6c 61 67 3a 0a 2a 2a 0a 2a 2a 20  EX] flag:.**.** 
1a3a0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c  <dl>.** <dt>[SQL
1a3b0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
1a3c0 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
1a3d0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1a3e0 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
1a3f0 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
1a400 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
1a410 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
1a420 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
1a430 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a   returned.</dd>.
1a440 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54  **.** <dt>[SQLIT
1a450 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1a460 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1a470 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1a480 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
1a490 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
1a4a0 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
1a4b0 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
1a4c0 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
1a4d0 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
1a4e0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
1a4f0 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
1a500 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
1a510 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
1a520 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
1a530 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
1a540 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  eturned.</dd>.**
1a550 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  .** <dt>[SQLITE_
1a560 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
1a570 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
1a580 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
1a590 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1a5a0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
1a5b0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
1a5c0 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
1a5d0 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f  s it if.** it do
1a5e0 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  es not already e
1a5f0 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68  xist. This is th
1a600 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  e behavior that 
1a610 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
1a620 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
1a630 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
1a640 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 0a  _open16().</dd>.
1a650 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </dl>.**.** I
1a660 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
1a670 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
1a680 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  pen_v2() is not 
1a690 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  one of the.** co
1a6a0 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
1a6b0 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66   above or one of
1a6c0 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e   the combination
1a6d0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f  s shown above co
1a6e0 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74  mbined.** with t
1a6f0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1a700 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 2c 20 74  NOMUTEX] flag, t
1a710 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1a720 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
1a730 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 51 4c  *.** If the [SQL
1a740 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
1a750 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
1a760 68 65 6e 20 6d 75 74 65 78 65 73 20 6f 6e 20 74  hen mutexes on t
1a770 68 65 0a 2a 2a 20 6f 70 65 6e 65 64 20 5b 64 61  he.** opened [da
1a780 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a790 6e 5d 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  n] are disabled 
1a7a0 61 6e 64 20 74 68 65 20 61 70 70 6c 69 61 74 69  and the appliati
1a7b0 6f 6e 20 6d 75 73 74 0a 2a 2a 20 69 6e 73 75 72  on must.** insur
1a7c0 65 20 74 68 61 74 20 61 63 63 65 73 73 20 74 6f  e that access to
1a7d0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
1a7e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 69  onnection] and i
1a7f0 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ts associated.**
1a800 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1a810 6d 65 6e 74 73 5d 20 69 73 20 73 65 72 69 61 6c  ments] is serial
1a820 69 7a 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  ized.  The [SQLI
1a830 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
1a840 20 66 6c 61 67 0a 2a 2a 20 69 73 20 74 68 65 20   flag.** is the 
1a850 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
1a860 20 69 73 20 53 51 4c 69 74 65 20 69 73 20 63 6f   is SQLite is co
1a870 6e 66 69 67 75 72 65 64 20 75 73 69 6e 67 20 74  nfigured using t
1a880 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
1a890 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
1a8a0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
1a8b0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
1a8c0 5d 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  ] options.** to 
1a8d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
1a8e0 29 5d 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  )].  The [SQLITE
1a8f0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
1a900 6c 61 67 20 6f 6e 6c 79 20 6d 61 6b 65 73 20 61  lag only makes a
1a910 0a 2a 2a 20 64 69 66 66 65 72 65 6e 63 65 20 77  .** difference w
1a920 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e  hen SQLite is in
1a930 20 69 74 73 20 64 65 66 61 75 6c 74 20 5b 53 51   its default [SQ
1a940 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
1a950 41 4c 49 5a 45 44 5d 20 6d 6f 64 65 2e 0a 2a 2a  ALIZED] mode..**
1a960 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e  .** If the filen
1a970 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ame is ":memory:
1a980 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  ", then a privat
1a990 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d  e, temporary in-
1a9a0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a  memory database.
1a9b0 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  ** is created fo
1a9c0 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
1a9d0 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72  .  This in-memor
1a9e0 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
1a9f0 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
1aa00 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1aa10 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
1aa20 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
1aa30 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
1aa40 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
1aa50 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
1aa60 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
1aa70 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
1aa80 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
1aa90 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
1aaa0 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
1aab0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
1aac0 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
1aad0 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
1aae0 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
1aaf0 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
1ab00 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
1ab10 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
1ab20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
1ab30 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
1ab40 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ty..**.** If the
1ab50 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20   filename is an 
1ab60 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
1ab70 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
1ab80 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69  mporary.** on-di
1ab90 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
1aba0 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 54 68   be created.  Th
1abb0 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
1abc0 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
1abd0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
1abe0 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
1abf0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1ac00 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
1ac10 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75  d..**.** The fou
1ac20 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
1ac30 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1ac40 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
1ac50 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
1ac60 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
1ac70 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
1ac80 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
1ac90 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
1aca0 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
1acb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
1acc0 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20 74 68  ould use.  If th
1acd0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1ace0 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
1acf0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
1ad00 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
1ad10 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
1ad20 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e   used..**.** <b>
1ad30 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
1ad40 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
1ad50 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f  encoding used fo
1ad60 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  r the filename a
1ad70 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71  rgument.** of sq
1ad80 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1ad90 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1ada0 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38  () must be UTF-8
1adb0 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a  , not whatever.*
1adc0 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75  * codepage is cu
1add0 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e  rrently defined.
1ade0 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74    Filenames cont
1adf0 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69  aining internati
1ae00 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65  onal.** characte
1ae10 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  rs must be conve
1ae20 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72  rted to UTF-8 pr
1ae30 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74  ior to passing t
1ae40 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  hem into.** sqli
1ae50 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
1ae60 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
1ae70 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1ae80 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 31  S:.**.** {H12701
1ae90 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  } The [sqlite3_o
1aea0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
1aeb0 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a  _open16()], and.
1aec0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1aed0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
1aee0 69 6e 74 65 72 66 61 63 65 73 20 63 72 65 61 74  interfaces creat
1aef0 65 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20  e a new.**      
1af00 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
1af10 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69  nnection] associ
1af20 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 20 20 20  ated with.**    
1af30 20 20 20 20 20 20 74 68 65 20 64 61 74 61 62 61        the databa
1af40 73 65 20 66 69 6c 65 20 67 69 76 65 6e 20 69 6e  se file given in
1af50 20 74 68 65 69 72 20 66 69 72 73 74 20 70 61 72   their first par
1af60 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ameter..**.** {H
1af70 31 32 37 30 32 7d 20 54 68 65 20 66 69 6c 65 6e  12702} The filen
1af80 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
1af90 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
1afa0 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20  TF-8.**         
1afb0 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70   for [sqlite3_op
1afc0 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  en()] and [sqlit
1afd0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e  e3_open_v2()] an
1afe0 64 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20 20  d as UTF-16.**  
1aff0 20 20 20 20 20 20 20 20 69 6e 20 74 68 65 20 6e          in the n
1b000 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1b010 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70   for [sqlite3_op
1b020 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  en16()]..**.** {
1b030 48 31 32 37 30 33 7d 20 41 20 73 75 63 63 65 73  H12703} A succes
1b040 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
1b050 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  of [sqlite3_open
1b060 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1b070 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  en16()],.**     
1b080 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33       or [sqlite3
1b090 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 72 69 74  _open_v2()] writ
1b0a0 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  es a pointer to 
1b0b0 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20  a new.**        
1b0c0 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e    [database conn
1b0d0 65 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 2a 70 70  ection] into *pp
1b0e0 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30  Db..**.** {H1270
1b0f0 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
1b100 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
1b110 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
1b120 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1b130 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1b140 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75   interfaces retu
1b150 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 75  rn [SQLITE_OK] u
1b160 70 6f 6e 20 73 75 63 63 65 73 73 2c 0a 2a 2a 20  pon success,.** 
1b170 20 20 20 20 20 20 20 20 20 6f 72 20 61 6e 20 61           or an a
1b180 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
1b190 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75  r code] on failu
1b1a0 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30  re..**.** {H1270
1b1b0 36 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 74  6} The default t
1b1c0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ext encoding for
1b1d0 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 65 20   a new database 
1b1e0 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
1b1f0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1b200 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73  e3_open()] or [s
1b210 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1b220 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 2e  ] will be UTF-8.
1b230 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 37 7d 20  .**.** {H12707} 
1b240 54 68 65 20 64 65 66 61 75 6c 74 20 74 65 78 74  The default text
1b250 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 20   encoding for a 
1b260 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 72 65  new database cre
1b270 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ated using.**   
1b280 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1b290 6f 70 65 6e 31 36 28 29 5d 20 77 69 6c 6c 20 62  open16()] will b
1b2a0 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
1b2b0 7b 48 31 32 37 30 39 7d 20 54 68 65 20 5b 73 71  {H12709} The [sq
1b2c0 6c 69 74 65 33 5f 6f 70 65 6e 28 46 2c 44 29 5d  lite3_open(F,D)]
1b2d0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 71   interface is eq
1b2e0 75 69 76 61 6c 65 6e 74 20 74 6f 0a 2a 2a 20 20  uivalent to.**  
1b2f0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1b300 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 30  _open_v2(F,D,G,0
1b310 29 5d 20 77 68 65 72 65 20 74 68 65 20 47 20 70  )] where the G p
1b320 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20  arameter is.**  
1b330 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
1b340 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 7c  OPEN_READWRITE]|
1b350 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
1b360 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ATE]..**.** {H12
1b370 37 31 31 7d 20 49 66 20 74 68 65 20 47 20 70 61  711} If the G pa
1b380 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
1b390 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c  te3_open_v2(F,D,
1b3a0 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74  G,V)] contains t
1b3b0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  he.**          b
1b3c0 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  it value [SQLITE
1b3d0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20  _OPEN_READONLY] 
1b3e0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
1b3f0 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20  e is opened.**  
1b400 20 20 20 20 20 20 20 20 66 6f 72 20 72 65 61 64          for read
1b410 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ing only..**.** 
1b420 7b 48 31 32 37 31 32 7d 20 49 66 20 74 68 65 20  {H12712} If the 
1b430 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  G parameter to [
1b440 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1b450 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69  F,D,G,V)] contai
1b460 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
1b470 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51     bit value [SQ
1b480 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1b490 49 54 45 5d 20 74 68 65 6e 20 74 68 65 20 64 61  ITE] then the da
1b4a0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1b4b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 61  .**          rea
1b4c0 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
1b4d0 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
1b4e0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c   for reading onl
1b4f0 79 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  y if the.**     
1b500 20 20 20 20 20 66 69 6c 65 20 69 73 20 77 72 69       file is wri
1b510 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
1b520 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
1b530 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  stem..**.** {H12
1b540 37 31 33 7d 20 49 66 20 74 68 65 20 47 20 70 61  713} If the G pa
1b550 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
1b560 74 65 33 5f 6f 70 65 6e 28 76 32 28 46 2c 44 2c  te3_open(v2(F,D,
1b570 47 2c 56 29 5d 20 6f 6d 69 74 73 20 74 68 65 0a  G,V)] omits the.
1b580 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20  **          bit 
1b590 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50  value [SQLITE_OP
1b5a0 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 74  EN_CREATE] and t
1b5b0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
1b5c0 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20   not.**         
1b5d0 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73   previously exis
1b5e0 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
1b5f0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  eturned..**.** {
1b600 48 31 32 37 31 34 7d 20 49 66 20 74 68 65 20 47  H12714} If the G
1b610 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
1b620 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32 28 46  qlite3_open(v2(F
1b630 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e  ,D,G,V)] contain
1b640 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
1b650 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c    bit value [SQL
1b660 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
1b670 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
1b680 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20  e does not.**   
1b690 20 20 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c         previousl
1b6a0 79 20 65 78 69 73 74 2c 20 74 68 65 6e 20 61 6e  y exist, then an
1b6b0 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
1b6c0 20 74 6f 20 63 72 65 61 74 65 20 61 6e 64 0a 2a   to create and.*
1b6d0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 69 74 69  *          initi
1b6e0 61 6c 69 7a 65 20 74 68 65 20 64 61 74 61 62 61  alize the databa
1b6f0 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31  se..**.** {H1271
1b700 37 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61  7} If the filena
1b710 6d 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  me argument to [
1b720 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
1b730 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1b740 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
1b750 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
1b760 6e 5f 76 32 28 29 5d 20 69 73 20 22 3a 6d 65 6d  n_v2()] is ":mem
1b770 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70  ory:", then an p
1b780 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20  rivate,.**      
1b790 20 20 20 20 65 70 68 65 6d 65 72 61 6c 2c 20 69      ephemeral, i
1b7a0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
1b7b0 65 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  e is created for
1b7c0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
1b7d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f  .**          <to
1b7e0 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50 45  do>Is SQLITE_OPE
1b7f0 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45 5f  N_CREATE|SQLITE_
1b800 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 72  OPEN_READWRITE r
1b810 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20 20  equired.**      
1b820 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f      in sqlite3_o
1b830 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e  pen_v2()?</todo>
1b840 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 39 7d 20  .**.** {H12719} 
1b850 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1b860 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d  is NULL or an em
1b870 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
1b880 20 61 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20   a private,.**  
1b890 20 20 20 20 20 20 20 20 65 70 68 65 6d 65 72 61          ephemera
1b8a0 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  l on-disk databa
1b8b0 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
1b8c0 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ed..**          
1b8d0 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f  <todo>Is SQLITE_
1b8e0 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49  OPEN_CREATE|SQLI
1b8f0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1b900 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 20  E required.**   
1b910 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74 65         in sqlite
1b920 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f  3_open_v2()?</to
1b930 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32  do>.**.** {H1272
1b940 31 7d 20 54 68 65 20 5b 64 61 74 61 62 61 73 65  1} The [database
1b950 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 72 65   connection] cre
1b960 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ated by [sqlite3
1b970 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56  _open_v2(F,D,G,V
1b980 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  )].**          w
1b990 69 6c 6c 20 75 73 65 20 74 68 65 20 5b 73 71 6c  ill use the [sql
1b9a0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1b9b0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
1b9c0 68 65 20 56 20 70 61 72 61 6d 65 74 65 72 2c 0a  he V parameter,.
1b9d0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74  **          or t
1b9e0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1b9f0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1ba00 69 66 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70  if V is a NULL p
1ba10 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ointer..**.** {H
1ba20 31 32 37 32 33 7d 20 54 77 6f 20 5b 64 61 74 61  12723} Two [data
1ba30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1ba40 5d 20 77 69 6c 6c 20 73 68 61 72 65 20 61 20 63  ] will share a c
1ba50 6f 6d 6d 6f 6e 20 63 61 63 68 65 20 69 66 20 62  ommon cache if b
1ba60 6f 74 68 20 77 65 72 65 0a 2a 2a 20 20 20 20 20  oth were.**     
1ba70 20 20 20 20 20 6f 70 65 6e 65 64 20 77 69 74 68       opened with
1ba80 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 77 68   the same VFS wh
1ba90 69 6c 65 20 5b 73 68 61 72 65 64 20 63 61 63 68  ile [shared cach
1baa0 65 20 6d 6f 64 65 5d 20 77 61 73 20 65 6e 61 62  e mode] was enab
1bab0 6c 65 64 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  led and.**      
1bac0 20 20 20 20 69 66 20 62 6f 74 68 20 66 69 6c 65      if both file
1bad0 6e 61 6d 65 73 20 63 6f 6d 70 61 72 65 20 65 71  names compare eq
1bae0 75 61 6c 20 75 73 69 6e 67 20 6d 65 6d 63 6d 70  ual using memcmp
1baf0 28 29 20 61 66 74 65 72 20 68 61 76 69 6e 67 20  () after having 
1bb00 62 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  been.**         
1bb10 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 74 68   processed by th
1bb20 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  e [sqlite3_vfs |
1bb30 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 5d 20   xFullPathname] 
1bb40 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 56 46  method of the VF
1bb50 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  S..*/.int sqlite
1bb60 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
1bb70 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1bb80 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1bb90 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1bba0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1bbb0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
1bbc0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1bbd0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
1bbe0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
1bbf0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
1bc00 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
1bc10 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
1bc20 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
1bc30 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
1bc40 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
1bc50 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
1bc60 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
1bc70 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
1bc80 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1bc90 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1bca0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1bcb0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1bcc0 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
1bcd0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1bce0 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
1bcf0 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
1bd00 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
1bd10 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
1bd20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
1bd30 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
1bd40 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
1bd50 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
1bd60 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
1bd70 61 67 65 73 20 7b 48 31 32 38 30 30 7d 20 3c 53  ages {H12800} <S
1bd80 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  60200>.**.** The
1bd90 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
1bda0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
1bdb0 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
1bdc0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
1bdd0 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
1bde0 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20  esult code] for 
1bdf0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
1be00 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a  failed sqlite3_*
1be10 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73   API call.** ass
1be20 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b  ociated with a [
1be30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1be40 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72  ion]. If a prior
1be50 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64   API call failed
1be60 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74  .** but the most
1be70 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c   recent API call
1be80 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20   succeeded, the 
1be90 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
1bea0 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72  m.** sqlite3_err
1beb0 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69  code() is undefi
1bec0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
1bed0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
1bee0 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
1bef0 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
1bf00 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
1bf10 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
1bf20 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
1bf30 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
1bf40 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
1bf50 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f  ctively..** Memo
1bf60 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
1bf70 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
1bf80 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
1bf90 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
1bfa0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
1bfb0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
1bfc0 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
1bfd0 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
1bfe0 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
1bff0 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
1c000 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
1c010 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
1c020 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
1c030 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
1c040 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
1c050 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
1c060 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63  * If an interfac
1c070 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c  e fails with SQL
1c080 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74  ITE_MISUSE, that
1c090 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72   means the inter
1c0a0 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f  face.** was invo
1c0b0 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ked incorrectly 
1c0c0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
1c0d0 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73  on.  In that cas
1c0e0 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20  e, the.** error 
1c0f0 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
1c100 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20   may or may not 
1c110 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e  be set..**.** IN
1c120 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1c130 7b 48 31 32 38 30 31 7d 20 54 68 65 20 5b 73 71  {H12801} The [sq
1c140 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29  lite3_errcode(D)
1c150 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
1c160 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a  rns the numeric.
1c170 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 72 65 73  **          [res
1c180 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78  ult code] or [ex
1c190 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
1c1a0 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74  de] for the most
1c1b0 20 72 65 63 65 6e 74 6c 79 0a 2a 2a 20 20 20 20   recently.**    
1c1c0 20 20 20 20 20 20 66 61 69 6c 65 64 20 69 6e 74        failed int
1c1d0 65 72 66 61 63 65 20 63 61 6c 6c 20 61 73 73 6f  erface call asso
1c1e0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1c1f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1c200 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
1c210 48 31 32 38 30 33 7d 20 54 68 65 20 5b 73 71 6c  H12803} The [sql
1c220 69 74 65 33 5f 65 72 72 6d 73 67 28 44 29 5d 20  ite3_errmsg(D)] 
1c230 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
1c240 6d 73 67 31 36 28 44 29 5d 0a 2a 2a 20 20 20 20  msg16(D)].**    
1c250 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
1c260 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
1c270 6c 61 6e 67 75 61 67 65 20 74 65 78 74 20 74 68  language text th
1c280 61 74 20 64 65 73 63 72 69 62 65 73 0a 2a 2a 20  at describes.** 
1c290 20 20 20 20 20 20 20 20 20 74 68 65 20 65 72 72           the err
1c2a0 6f 72 20 69 6e 20 74 68 65 20 6d 6f 73 74 6c 79  or in the mostly
1c2b0 20 72 65 63 65 6e 74 6c 79 20 66 61 69 6c 65 64   recently failed
1c2c0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2c   interface call,
1c2d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63  .**          enc
1c2e0 6f 64 65 64 20 61 73 20 65 69 74 68 65 72 20 55  oded as either U
1c2f0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
1c300 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
1c310 2a 2a 20 7b 48 31 32 38 30 37 7d 20 54 68 65 20  ** {H12807} The 
1c320 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
1c330 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   by [sqlite3_err
1c340 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  msg()] and [sqli
1c350 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a  te3_errmsg16()].
1c360 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20  **          are 
1c370 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
1c380 6e 65 78 74 20 53 51 4c 69 74 65 20 69 6e 74 65  next SQLite inte
1c390 72 66 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  rface call..**.*
1c3a0 2a 20 7b 48 31 32 38 30 38 7d 20 43 61 6c 6c 73  * {H12808} Calls
1c3b0 20 74 6f 20 41 50 49 20 72 6f 75 74 69 6e 65 73   to API routines
1c3c0 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 72 65 74   that do not ret
1c3d0 75 72 6e 20 61 6e 20 65 72 72 6f 72 20 63 6f 64  urn an error cod
1c3e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 28 65  e.**          (e
1c3f0 78 61 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33  xample: [sqlite3
1c400 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20  _data_count()]) 
1c410 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20  do not.**       
1c420 20 20 20 63 68 61 6e 67 65 20 74 68 65 20 65 72     change the er
1c430 72 6f 72 20 63 6f 64 65 20 6f 72 20 6d 65 73 73  ror code or mess
1c440 61 67 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a  age returned by.
1c450 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1c460 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c  ite3_errcode()],
1c470 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1c480 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
1c490 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a  _errmsg16()]..**
1c4a0 0a 2a 2a 20 7b 48 31 32 38 30 39 7d 20 49 6e 74  .** {H12809} Int
1c4b0 65 72 66 61 63 65 73 20 74 68 61 74 20 61 72 65  erfaces that are
1c4c0 20 6e 6f 74 20 61 73 73 6f 63 69 61 74 65 64 20   not associated 
1c4d0 77 69 74 68 20 61 20 73 70 65 63 69 66 69 63 0a  with a specific.
1c4e0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
1c4f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c500 5d 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20  ] (examples:.** 
1c510 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1c520 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20  3_mprintf()] or 
1c530 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
1c540 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 0a  shared_cache()].
1c550 2a 2a 20 20 20 20 20 20 20 20 20 20 64 6f 20 6e  **          do n
1c560 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
1c570 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
1c580 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1c590 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
1c5a0 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  , [sqlite3_errms
1c5b0 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  g()], or [sqlite
1c5c0 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a  3_errmsg16()]..*
1c5d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
1c5e0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
1c5f0 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  b);.const char *
1c600 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
1c610 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
1c620 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72  void *sqlite3_er
1c630 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29  rmsg16(sqlite3*)
1c640 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c650 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  F: SQL Statement
1c660 20 4f 62 6a 65 63 74 20 7b 48 31 33 30 30 30 7d   Object {H13000}
1c670 20 3c 48 31 33 30 31 30 3e 0a 2a 2a 20 4b 45 59   <H13010>.** KEY
1c680 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
1c690 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
1c6a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
1c6b0 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
1c6c0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
1c6d0 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
1c6e0 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
1c6f0 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ment..** This ob
1c700 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c  ject is variousl
1c710 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72  y known as a "pr
1c720 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1c730 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69  " or a.** "compi
1c740 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
1c750 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20  t" or simply as 
1c760 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a  a "statement"..*
1c770 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66  *.** The life of
1c780 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a   a statement obj
1c790 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69  ect goes somethi
1c7a0 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ng like this:.**
1c7b0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
1c7c0 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65   Create the obje
1c7d0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
1c7e0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1c7f0 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  or a related.** 
1c800 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a       function..*
1c810 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
1c820 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61  es to [host para
1c830 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
1c840 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1c850 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
1c860 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
1c870 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
1c880 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
1c890 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
1c8a0 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
1c8b0 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74  > Reset the stat
1c8c0 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
1c8d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
1c8e0 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
1c8f0 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
1c900 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
1c910 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
1c920 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
1c930 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
1c940 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1c950 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
1c960 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65   Refer to docume
1c970 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  ntation on indiv
1c980 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62  idual methods ab
1c990 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ove for addition
1c9a0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1c9b0 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
1c9c0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
1c9d0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
1c9e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c9f0 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
1ca00 20 7b 48 31 32 37 36 30 7d 20 3c 53 32 30 36 30   {H12760} <S2060
1ca10 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  0>.**.** This in
1ca20 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74  terface allows t
1ca30 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f  he size of vario
1ca40 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  us constructs to
1ca50 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f   be limited.** o
1ca60 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  n a connection b
1ca70 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  y connection bas
1ca80 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  is.  The first p
1ca90 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
1caa0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1cab0 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c  nection] whose l
1cac0 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65  imit is to be se
1cad0 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54  t or queried.  T
1cae0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1caf0 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66  ameter is one of
1cb00 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65   the [limit cate
1cb10 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66  gories] that def
1cb20 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f  ine a.** class o
1cb30 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  f constructs to 
1cb40 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e  be size limited.
1cb50 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
1cb60 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
1cb70 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68  new limit for th
1cb80 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 54  at construct.  T
1cb90 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
1cba0 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69  rns the old limi
1cbb0 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
1cbc0 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
1cbd0 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
1cbe0 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
1cbf0 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72 20 74  hanged..** For t
1cc00 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  he limit categor
1cc10 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49  y of SQLITE_LIMI
1cc20 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73 20 61  T_XYZ there is a
1cc30 20 68 61 72 64 20 75 70 70 65 72 0a 2a 2a 20 62   hard upper.** b
1cc40 6f 75 6e 64 20 73 65 74 20 62 79 20 61 20 63 6f  ound set by a co
1cc50 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20 70 72 65  mpile-time C pre
1cc60 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
1cc70 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f 4d 41 58  named SQLITE_MAX
1cc80 5f 58 59 5a 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  _XYZ..** (The "_
1cc90 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
1cca0 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
1ccb0 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41  o "_MAX_".).** A
1ccc0 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
1ccd0 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
1cce0 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
1ccf0 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
1cd00 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
1cd10 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
1cd20 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20  er limit..**.** 
1cd30 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74 73 20  Run time limits 
1cd40 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
1cd50 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74   use in applicat
1cd60 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65  ions that manage
1cd70 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f  .** both their o
1cd80 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  wn internal data
1cd90 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61  base and also da
1cda0 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65  tabases that are
1cdb0 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62   controlled.** b
1cdc0 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65  y untrusted exte
1cdd0 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41  rnal sources.  A
1cde0 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63  n example applic
1cdf0 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61  ation might be a
1ce00 0a 2a 2a 20 77 65 62 62 72 6f 77 73 65 72 20 74  .** webbrowser t
1ce10 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20  hat has its own 
1ce20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74  databases for st
1ce30 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e  oring history an
1ce40 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61  d.** separate da
1ce50 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c  tabases controll
1ce60 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74  ed by JavaScript
1ce70 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f   applications do
1ce80 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20  wnloaded.** off 
1ce90 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54  the Internet.  T
1cea0 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  he internal data
1ceb0 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76  bases can be giv
1cec0 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c  en the.** large,
1ced0 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e   default limits.
1cee0 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61    Databases mana
1cef0 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20  ged by external 
1cf00 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62  sources can.** b
1cf10 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61  e given much sma
1cf20 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69  ller limits desi
1cf30 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20  gned to prevent 
1cf40 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76  a denial of serv
1cf50 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20  ice.** attack.  
1cf60 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74  Developers might
1cf70 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73   also want to us
1cf80 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  e the [sqlite3_s
1cf90 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
1cfa0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f  .** interface to
1cfb0 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c   further control
1cfc0 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20   untrusted SQL. 
1cfd0 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
1cfe0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65   database.** cre
1cff0 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75  ated by an untru
1d000 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20  sted script can 
1d010 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69  be contained usi
1d020 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70  ng the.** [max_p
1d030 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
1d040 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72  MA]..**.** New r
1d050 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61  un-time limit ca
1d060 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20  tegories may be 
1d070 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
1d080 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
1d090 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1d0a0 2a 20 7b 48 31 32 37 36 32 7d 20 41 20 73 75 63  * {H12762} A suc
1d0b0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
1d0c0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44  [sqlite3_limit(D
1d0d0 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69  ,C,V)] where V i
1d0e0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f  s.**          po
1d0f0 73 69 74 69 76 65 20 63 68 61 6e 67 65 73 20 74  sitive changes t
1d100 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20  he limit on the 
1d110 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75 63  size of construc
1d120 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  t C in the.**   
1d130 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
1d140 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74   connection] D t
1d150 6f 20 74 68 65 20 6c 65 73 73 65 72 20 6f 66 20  o the lesser of 
1d160 56 20 61 6e 64 20 74 68 65 20 68 61 72 64 20 75  V and the hard u
1d170 70 70 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  pper.**         
1d180 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73 69   bound on the si
1d190 7a 65 20 6f 66 20 43 20 74 68 61 74 20 69 73 20  ze of C that is 
1d1a0 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
1d1b0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ime..**.** {H127
1d1c0 36 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  66} A successful
1d1d0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1d1e0 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20  3_limit(D,C,V)] 
1d1f0 77 68 65 72 65 20 56 20 69 73 20 6e 65 67 61 74  where V is negat
1d200 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
1d210 6c 65 61 76 65 73 20 74 68 65 20 73 74 61 74 65  leaves the state
1d220 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
1d230 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
1d240 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a  unchanged..**.**
1d250 20 7b 48 31 32 37 36 39 7d 20 41 20 73 75 63 63   {H12769} A succ
1d260 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
1d270 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c  sqlite3_limit(D,
1d280 43 2c 56 29 5d 20 72 65 74 75 72 6e 73 20 74 68  C,V)] returns th
1d290 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  e.**          va
1d2a0 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
1d2b0 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20   on the size of 
1d2c0 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 20 74  construct C in t
1d2d0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
1d2e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d2f0 69 6f 6e 5d 20 44 20 61 73 20 69 74 20 77 61 73  ion] D as it was
1d300 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61   prior to the ca
1d310 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ll..*/.int sqlit
1d320 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
1d330 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
1d340 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
1d350 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1d360 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
1d370 65 73 20 7b 48 31 32 37 39 30 7d 20 3c 48 31 32  es {H12790} <H12
1d380 37 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  760>.** KEYWORDS
1d390 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  : {limit categor
1d3a0 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  y} {limit catego
1d3b0 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
1d3c0 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
1d3d0 6e 65 20 76 61 72 69 6f 75 73 20 61 73 70 65 63  ne various aspec
1d3e0 74 73 20 6f 66 20 61 20 5b 64 61 74 61 62 61 73  ts of a [databas
1d3f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
1d400 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 69 6d   that can be lim
1d410 69 74 65 64 20 69 6e 20 73 69 7a 65 20 62 79 20  ited in size by 
1d420 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1d430 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
1d440 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
1d450 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
1d460 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73  s are as follows
1d470 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  :.**.** <dl>.** 
1d480 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1d490 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1d4a0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1d4b0 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69  size of any stri
1d4c0 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61  ng or BLOB or ta
1d4d0 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a  ble row.<dd>.**.
1d4e0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1d4f0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
1d500 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1d510 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1d520 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1d530 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
1d540 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
1d550 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OLUMN</dt>.** <d
1d560 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1d570 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
1d580 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e  in a table defin
1d590 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a  ition or in the.
1d5a0 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ** result set of
1d5b0 20 61 20 53 45 4c 45 43 54 20 6f 72 20 74 68 65   a SELECT or the
1d5c0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1d5d0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
1d5e0 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
1d5f0 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
1d600 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
1d610 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1d620 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
1d630 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
1d640 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
1d650 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
1d660 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
1d670 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  pression.</dd>.*
1d680 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1d690 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
1d6a0 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ELECT</dt>.** <d
1d6b0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1d6c0 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
1d6d0 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45   a compound SELE
1d6e0 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  CT statement.</d
1d6f0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
1d700 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
1d710 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
1d720 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1d730 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
1d740 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
1d750 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
1d760 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1d770 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
1d780 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ent.</dd>.**.** 
1d790 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1d7a0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
1d7b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1d7c0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1d7d0 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
1d7e0 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a  unction.</dd>.**
1d7f0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
1d800 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64  IMIT_ATTACHED</d
1d810 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1d820 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1d830 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
1d840 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  es.</dd>.**.** <
1d850 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1d860 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
1d870 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
1d880 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
1d890 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
1d8a0 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
1d8b0 65 20 4c 49 4b 45 20 6f 72 0a 2a 2a 20 47 4c 4f  e LIKE or.** GLO
1d8c0 42 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64  B operators.</dd
1d8d0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1d8e0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
1d8f0 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
1d900 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1d910 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72 69 61   number of varia
1d920 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c 20 73  bles in an SQL s
1d930 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 63 61  tatement that ca
1d940 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f  n.** be bound.</
1d950 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  dd>.** </dl>.*/.
1d960 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1d970 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
1d980 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
1d990 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d9a0 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
1d9b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1d9c0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
1d9d0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
1d9e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1d9f0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
1da00 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
1da10 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
1da20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
1da30 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
1da40 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
1da50 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
1da60 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
1da70 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
1da80 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
1da90 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
1daa0 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
1dab0 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
1dac0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
1dad0 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
1dae0 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
1daf0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
1db00 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
1db10 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
1db20 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
1db30 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
1db40 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a          9../*.**
1db50 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
1db60 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74  ling An SQL Stat
1db70 65 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d 20 3c  ement {H13010} <
1db80 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S10000>.** KEYWO
1db90 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
1dba0 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
1dbb0 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
1dbc0 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20  n SQL query, it 
1dbd0 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f  must first be co
1dbe0 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79  mpiled into a by
1dbf0 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72  te-code.** progr
1dc00 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  am using one of 
1dc10 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
1dc20 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
1dc30 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
1dc40 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
1dc50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
1dc60 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
1dc70 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ior call to [sql
1dc80 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
1dc90 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1dca0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ] or [sqlite3_op
1dcb0 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  en16()]..**.** T
1dcc0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1dcd0 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74  nt, "zSql", is t
1dce0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  he statement to 
1dcf0 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63  be compiled, enc
1dd00 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65  oded.** as eithe
1dd10 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
1dd20 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  6.  The sqlite3_
1dd30 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71  prepare() and sq
1dd40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1dd50 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
1dd60 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20   use UTF-8, and 
1dd70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1dd80 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  6() and sqlite3_
1dd90 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a  prepare16_v2().*
1dda0 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a  * use UTF-16..**
1ddb0 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74 65  .** If the nByte
1ddc0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73   argument is les
1ddd0 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65  s than zero, the
1dde0 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
1ddf0 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
1de00 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
1de10 72 2e 20 49 66 20 6e 42 79 74 65 20 69 73 20 6e  r. If nByte is n
1de20 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
1de30 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69  n it is the maxi
1de40 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  mum.** number of
1de50 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f    bytes read fro
1de60 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42  m zSql.  When nB
1de70 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
1de80 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c  ive, the.** zSql
1de90 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20   string ends at 
1dea0 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74  either the first
1deb0 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30   '\000' or '\u00
1dec0 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72  00' character or
1ded0 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68  .** the nByte-th
1dee0 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72   byte, whichever
1def0 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66   comes first. If
1df00 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77   the caller know
1df10 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75  s.** that the su
1df20 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
1df30 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
1df40 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61   then there is a
1df50 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72   small.** perfor
1df60 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
1df70 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20  to be gained by 
1df80 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
1df90 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a   parameter that.
1dfa0 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74  ** is equal to t
1dfb0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
1dfc0 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20  es in the input 
1dfd0 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64  string <i>includ
1dfe0 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e  ing</i>.** the n
1dff0 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79  ul-terminator by
1e000 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61  tes..**.** *pzTa
1e010 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
1e020 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
1e030 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65   byte past the e
1e040 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  nd of the.** fir
1e050 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
1e060 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
1e070 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 20 63   routines only c
1e080 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
1e090 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
1e0a0 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
1e0b0 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
1e0c0 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d 61 69  ng to what remai
1e0d0 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65 64  ns.** uncompiled
1e0e0 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20  ..**.** *ppStmt 
1e0f0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
1e100 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
1e110 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1e120 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
1e130 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
1e140 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
1e150 29 5d 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  )].  If there is
1e160 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
1e170 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
1e180 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e  NULL.  If the in
1e190 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
1e1a0 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
1e1b0 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
1e1c0 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
1e1d0 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
1e1e0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
1e1f0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 41 31 33 30  o NULL..** {A130
1e200 31 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  18} The calling 
1e210 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73  procedure is res
1e220 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c  ponsible for del
1e230 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  eting the compil
1e240 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ed.** SQL statem
1e250 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
1e260 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
1e270 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
1e280 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
1e290 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20  .** On success, 
1e2a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
1e2b0 65 74 75 72 6e 65 64 2c 20 6f 74 68 65 72 77 69  eturned, otherwi
1e2c0 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
1e2d0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
1e2e0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1e2f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61  3_prepare_v2() a
1e300 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
1e310 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66  re16_v2() interf
1e320 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f  aces are.** reco
1e330 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
1e340 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68  new programs. Th
1e350 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65  e two older inte
1e360 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69  rfaces are retai
1e370 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77  ned.** for backw
1e380 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1e390 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
1e3a0 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
1e3b0 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22  ..** In the "v2"
1e3c0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
1e3d0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
1e3e0 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72  ent.** that is r
1e3f0 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71  eturned (the [sq
1e400 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
1e410 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63  ct) contains a c
1e420 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72  opy of the.** or
1e430 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
1e440 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
1e450 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1e460 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
1e470 2a 20 62 65 68 61 76 65 20 61 20 64 69 66 66 65  * behave a diffe
1e480 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77 61  rently in two wa
1e490 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
1e4a0 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65  * <li>.** If the
1e4b0 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
1e4c0 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
1e4d0 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
1e4e0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
1e4f0 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
1e500 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
1e510 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
1e520 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
1e530 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
1e540 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
1e550 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
1e560 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73  again.  If the s
1e570 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65  chema has change
1e580 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68  d in.** a way th
1e590 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61  at makes the sta
1e5a0 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72  tement no longer
1e5b0 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33   valid, [sqlite3
1e5c0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74  _step()] will st
1e5d0 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
1e5e0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20  QLITE_SCHEMA].  
1e5f0 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c  But unlike the l
1e600 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20  egacy behavior, 
1e610 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
1e620 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61  is.** now a fata
1e630 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e  l error.  Callin
1e640 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
1e650 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77  re_v2()] again w
1e660 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65  ill not make the
1e670 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61  .** error go awa
1e680 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73  y.  Note: use [s
1e690 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1e6a0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78   to find the tex
1e6b0 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73  t.** of the pars
1e6c0 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20 72  ing error that r
1e6d0 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51  esults in an [SQ
1e6e0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74  LITE_SCHEMA] ret
1e6f0 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  urn..** </li>.**
1e700 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e  .** <li>.** When
1e710 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
1e720 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1e730 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
1e740 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
1e750 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
1e760 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
1e770 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
1e780 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
1e790 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
1e7a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1e7b0 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
1e7c0 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
1e7d0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
1e7e0 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 79  lt code.** and y
1e7f0 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  ou would have to
1e800 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
1e810 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
1e820 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65  reset()] in orde
1e830 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65  r.** to find the
1e840 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
1e850 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
1e860 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
1e870 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
1e880 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
1e890 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
1e8a0 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
1e8b0 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
1e8c0 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  ly..** </li>.** 
1e8d0 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  </ol>.**.** INVA
1e8e0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
1e8f0 31 33 30 31 31 7d 20 54 68 65 20 5b 73 71 6c 69  13011} The [sqli
1e900 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a  te3_prepare(db,z
1e910 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a  Sql,...)] and.**
1e920 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1e930 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62  e3_prepare_v2(db
1e940 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65  ,zSql,...)] inte
1e950 72 66 61 63 65 73 20 69 6e 74 65 72 70 72 65 74  rfaces interpret
1e960 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1e970 20 74 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a   text in their z
1e980 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73  Sql parameter as
1e990 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48   UTF-8..**.** {H
1e9a0 31 33 30 31 32 7d 20 54 68 65 20 5b 73 71 6c 69  13012} The [sqli
1e9b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 64 62  te3_prepare16(db
1e9c0 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a  ,zSql,...)] and.
1e9d0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1e9e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1e9f0 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20  2(db,zSql,...)] 
1ea00 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65 72  interfaces inter
1ea10 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20  pret the.**     
1ea20 20 20 20 20 20 74 65 78 74 20 69 6e 20 74 68 65       text in the
1ea30 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65  ir zSql paramete
1ea40 72 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  r as UTF-16 in t
1ea50 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
1ea60 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  rder..**.** {H13
1ea70 30 31 33 7d 20 49 66 20 74 68 65 20 6e 42 79 74  013} If the nByt
1ea80 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  e argument to [s
1ea90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1eaa0 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c  2(db,zSql,nByte,
1eab0 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
1eac0 20 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e    and its varian
1ead0 74 73 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  ts is less than 
1eae0 7a 65 72 6f 2c 20 74 68 65 20 53 51 4c 20 74 65  zero, the SQL te
1eaf0 78 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  xt is.**        
1eb00 20 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c    read from zSql
1eb10 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
1eb20 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
1eb30 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
1eb40 7b 48 31 33 30 31 34 7d 20 49 66 20 74 68 65 20  {H13014} If the 
1eb50 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74  nByte argument t
1eb60 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
1eb70 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42  re_v2(db,zSql,nB
1eb80 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  yte,...)].**    
1eb90 20 20 20 20 20 20 61 6e 64 20 69 74 73 20 76 61        and its va
1eba0 72 69 61 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e 65  riants is non-ne
1ebb0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 74 20  gative, then at 
1ebc0 6d 6f 73 74 20 6e 42 79 74 65 73 20 62 79 74 65  most nBytes byte
1ebd0 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  s of.**         
1ebe0 20 53 51 4c 20 74 65 78 74 20 69 73 20 72 65 61   SQL text is rea
1ebf0 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a  d from zSql..**.
1ec00 2a 2a 20 7b 48 31 33 30 31 35 7d 20 49 6e 20 5b  ** {H13015} In [
1ec10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1ec20 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70  v2(db,zSql,N,P,p
1ec30 7a 54 61 69 6c 29 5d 20 61 6e 64 20 69 74 73 20  zTail)] and its 
1ec40 76 61 72 69 61 6e 74 73 0a 2a 2a 20 20 20 20 20  variants.**     
1ec50 20 20 20 20 20 69 66 20 74 68 65 20 7a 53 71 6c       if the zSql
1ec60 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
1ec70 61 69 6e 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  ains more than o
1ec80 6e 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ne SQL statement
1ec90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
1eca0 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
1ecb0 55 4c 4c 2c 20 74 68 65 6e 20 2a 70 7a 54 61 69  ULL, then *pzTai
1ecc0 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
1ecd0 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  nt to the.**    
1ece0 20 20 20 20 20 20 66 69 72 73 74 20 62 79 74 65        first byte
1ecf0 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
1ed00 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
1ed10 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
1ed20 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74  ..**          <t
1ed30 6f 64 6f 3e 57 68 61 74 20 64 6f 65 73 20 2a 70  odo>What does *p
1ed40 7a 54 61 69 6c 20 70 6f 69 6e 74 20 74 6f 20 69  zTail point to i
1ed50 66 20 74 68 65 72 65 20 69 73 20 6f 6e 65 20 73  f there is one s
1ed60 74 61 74 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e  tatement?</todo>
1ed70 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 36 7d 20  .**.** {H13016} 
1ed80 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
1ed90 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  l to [sqlite3_pr
1eda0 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c  epare_v2(db,zSql
1edb0 2c 4e 2c 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a  ,N,ppStmt,...)].
1edc0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 6f  **          or o
1edd0 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
1ede0 74 73 20 77 72 69 74 65 73 20 69 6e 74 6f 20 2a  ts writes into *
1edf0 70 70 53 74 6d 74 20 61 20 70 6f 69 6e 74 65 72  ppStmt a pointer
1ee00 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20   to a new.**    
1ee10 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
1ee20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 61 20  statement] or a 
1ee30 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20  pointer to NULL 
1ee40 69 66 20 7a 53 71 6c 20 63 6f 6e 74 61 69 6e 73  if zSql contains
1ee50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 74  .**          not
1ee60 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
1ee70 77 68 69 74 65 73 70 61 63 65 20 6f 72 20 63 6f  whitespace or co
1ee80 6d 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  mments..**.** {H
1ee90 31 33 30 31 39 7d 20 54 68 65 20 5b 73 71 6c 69  13019} The [sqli
1eea0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1eeb0 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20  ] interface and 
1eec0 69 74 73 20 76 61 72 69 61 6e 74 73 20 72 65 74  its variants ret
1eed0 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
1eee0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61  [SQLITE_OK] or a
1eef0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
1ef00 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20  rror code] upon 
1ef10 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b  failure..**.** {
1ef20 48 31 33 30 32 31 7d 20 42 65 66 6f 72 65 20 5b  H13021} Before [
1ef30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1ef40 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70  db,zSql,nByte,pp
1ef50 53 74 6d 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72  Stmt,pzTail)] or
1ef60 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20   its.**         
1ef70 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e   variants return
1ef80 73 20 61 6e 20 65 72 72 6f 72 20 28 61 6e 79 20  s an error (any 
1ef90 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
1efa0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 29 2c 0a 2a   [SQLITE_OK]),.*
1efb0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 79 20  *          they 
1efc0 66 69 72 73 74 20 73 65 74 20 2a 70 70 53 74 6d  first set *ppStm
1efd0 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  t to NULL..*/.in
1efe0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1eff0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
1f000 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1f010 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1f020 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1f030 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1f040 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1f050 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
1f060 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
1f070 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
1f080 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
1f090 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
1f0a0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
1f0b0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
1f0c0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
1f0d0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1f0e0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
1f0f0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
1f100 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
1f110 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
1f120 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
1f130 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
1f140 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1f150 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
1f160 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1f170 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1f180 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
1f190 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
1f1a0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1f1b0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1f1c0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1f1d0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1f1e0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1f1f0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1f200 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1f210 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1f220 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
1f230 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1f240 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1f250 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1f260 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1f270 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
1f280 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1f290 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1f2a0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1f2b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
1f2c0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1f2d0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
1f2e0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1f2f0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1f300 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1f310 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1f320 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1f330 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1f340 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1f350 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1f360 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1f370 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1f380 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1f390 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1f3a0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
1f3b0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1f3c0 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
1f3d0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1f3e0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1f3f0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1f400 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
1f410 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1f420 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
1f430 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1f440 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1f450 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1f460 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1f470 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1f480 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1f490 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1f4a0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1f4b0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
1f4c0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1f4d0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1f4e0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1f4f0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
1f500 49 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  IREF: Retrieving
1f510 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b   Statement SQL {
1f520 48 31 33 31 30 30 7d 20 3c 48 31 33 30 30 30 3e  H13100} <H13000>
1f530 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1f540 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
1f550 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20  d to retrieve a 
1f560 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68  saved copy of th
1f570 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51  e original.** SQ
1f580 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63  L text used to c
1f590 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65  reate a [prepare
1f5a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20  d statement] if 
1f5b0 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77  that statement w
1f5c0 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75  as.** compiled u
1f5d0 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
1f5e0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1f5f0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
1f600 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
1f610 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
1f620 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 31 7d  :.**.** {H13101}
1f630 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   If the [prepare
1f640 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73  d statement] pas
1f650 73 65 64 20 61 73 20 74 68 65 20 61 72 67 75 6d  sed as the argum
1f660 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ent to.**       
1f670 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28     [sqlite3_sql(
1f680 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  )] was compiled 
1f690 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
1f6a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1f6b0 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ()] or.**       
1f6c0 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
1f6d0 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 74 68 65  are16_v2()], the
1f6e0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29  n [sqlite3_sql()
1f6f0 5d 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  ] returns.**    
1f700 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65 72 20        a pointer 
1f710 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
1f720 61 74 65 64 20 73 74 72 69 6e 67 20 63 6f 6e 74  ated string cont
1f730 61 69 6e 69 6e 67 20 61 20 55 54 46 2d 38 20 72  aining a UTF-8 r
1f740 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20 20  endering.**     
1f750 20 20 20 20 20 6f 66 20 74 68 65 20 6f 72 69 67       of the orig
1f760 69 6e 61 6c 20 53 51 4c 20 73 74 61 74 65 6d 65  inal SQL stateme
1f770 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30  nt..**.** {H1310
1f780 32 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61  2} If the [prepa
1f790 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70  red statement] p
1f7a0 61 73 73 65 64 20 61 73 20 74 68 65 20 61 72 67  assed as the arg
1f7b0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20  ument to.**     
1f7c0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 71       [sqlite3_sq
1f7d0 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65  l()] was compile
1f7e0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
1f7f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1f800 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
1f810 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61    [sqlite3_prepa
1f820 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 5b 73  re16()], then [s
1f830 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 72 65  qlite3_sql()] re
1f840 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1f850 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  nter..**.** {H13
1f860 31 30 33 7d 20 54 68 65 20 73 74 72 69 6e 67 20  103} The string 
1f870 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1f880 69 74 65 33 5f 73 71 6c 28 53 29 5d 20 69 73 20  ite3_sql(S)] is 
1f890 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 0a  valid until the.
1f8a0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
1f8b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1f8c0 20 53 20 69 73 20 64 65 6c 65 74 65 64 20 75 73   S is deleted us
1f8d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
1f8e0 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f  alize(S)]..*/.co
1f8f0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1f900 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  3_sql(sqlite3_st
1f910 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
1f920 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
1f930 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
1f940 61 6c 75 65 20 4f 62 6a 65 63 74 20 7b 48 31 35  alue Object {H15
1f950 30 30 30 7d 20 0a 2a 2a 20 4b 45 59 57 4f 52 44  000} .** KEYWORD
1f960 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71  S: {protected sq
1f970 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e  lite3_value} {un
1f980 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1f990 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53  3_value}.**.** S
1f9a0 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
1f9b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1f9c0 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ect to represent
1f9d0 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74   all values.** t
1f9e0 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65  hat can be store
1f9f0 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20  d in a database 
1fa00 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73  table. SQLite us
1fa10 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
1fa20 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c  g.** for the val
1fa30 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 56  ues it stores. V
1fa40 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
1fa50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1fa60 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20  jects.** can be 
1fa70 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
1fa80 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
1fa90 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
1faa0 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
1fab0 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
1fac0 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
1fad0 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
1fae0 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
1faf0 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
1fb00 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
1fb10 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
1fb20 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
1fb30 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
1fb40 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
1fb50 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
1fb60 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
1fb70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
1fb80 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
1fb90 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
1fba0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
1fbb0 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
1fbc0 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e  .** whether or n
1fbd0 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61  ot it requires a
1fbe0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
1fbf0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  e3_value..**.** 
1fc00 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65  The terms "prote
1fc10 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f  cted" and "unpro
1fc20 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f  tected" refer to
1fc30 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a   whether or not.
1fc40 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65  ** a mutex is he
1fc50 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20  ld.  A internal 
1fc60 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
1fc70 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a  r a protected.**
1fc80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1fc90 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74  bject but no mut
1fca0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
1fcb0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  n unprotected.**
1fcc0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1fcd0 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74  bject.  If SQLit
1fce0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f  e is compiled to
1fcf0 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61   be single-threa
1fd00 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51  ded.** (with [SQ
1fd10 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fd20 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c  0] and with [sql
1fd30 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
1fd40 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a  )] returning 0).
1fd50 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20  ** or if SQLite 
1fd60 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66  is run in one of
1fd70 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d   reduced mutex m
1fd80 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  odes .** [SQLITE
1fd90 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
1fda0 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
1fdb0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
1fdc0 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  EAD].** then the
1fdd0 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
1fde0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
1fdf0 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
1fe00 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
1fe10 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
1fe20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20  and they can be 
1fe30 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65  used interchange
1fe40 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a  ably.  However,.
1fe50 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  ** for maximum c
1fe60 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
1fe70 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
1fe80 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
1fe90 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b  ons.** still mak
1fea0 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
1feb0 6e 20 62 65 74 77 65 65 6e 20 62 65 74 77 65 65  n between betwee
1fec0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
1fed0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
1fee0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1fef0 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
1ff00 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
1ff10 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
1ff20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1ff30 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70  jects that are p
1ff40 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74  assed as paramet
1ff50 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ers into the.** 
1ff60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1ff70 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  f [application-d
1ff80 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1ff90 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63  ions] are protec
1ffa0 74 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ted..** The sqli
1ffb0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1ffc0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1ffd0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1ffe0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
1fff0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
20000 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
20010 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
20020 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
20030 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
20040 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
20050 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
20060 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
20070 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
20080 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
20090 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
200a0 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
200b0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
200c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
200d0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
200e0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
200f0 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
20100 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
20110 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
20120 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
20130 74 20 7b 48 31 36 30 30 31 7d 0a 2a 2a 0a 2a 2a  t {H16001}.**.**
20140 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20   The context in 
20150 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e  which an SQL fun
20160 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69  ction executes i
20170 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a  s stored in an.*
20180 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  * sqlite3_contex
20190 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f 69  t object.  A poi
201a0 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
201b0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
201c0 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
201d0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
201e0 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
201f0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
20200 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
20210 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
20220 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
20230 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
20240 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
20250 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
20260 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
20270 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
20280 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
20290 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
202a0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
202b0 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
202c0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
202d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
202e0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
202f0 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
20300 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
20310 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
20320 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
20330 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
20340 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
20350 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
20360 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20370 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
20380 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
20390 74 65 6d 65 6e 74 73 20 7b 48 31 33 35 30 30 7d  tements {H13500}
203a0 20 3c 53 37 30 30 30 30 3e 0a 2a 2a 20 4b 45 59   <S70000>.** KEY
203b0 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72  WORDS: {host par
203c0 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61  ameter} {host pa
203d0 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20  rameters} {host 
203e0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a  parameter name}.
203f0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
20400 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51  L parameter} {SQ
20410 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70  L parameters} {p
20420 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
20430 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53  }.**.** In the S
20440 51 4c 20 73 74 72 69 6e 67 73 20 69 6e 70 75 74  QL strings input
20450 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
20460 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69  pare_v2()] and i
20470 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20  ts variants,.** 
20480 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20  literals may be 
20490 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 70 61  replaced by a pa
204a0 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65 20 6f  rameter in one o
204b0 66 20 74 68 65 73 65 20 66 6f 72 6d 73 3a 0a 2a  f these forms:.*
204c0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
204d0 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
204e0 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
204f0 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
20500 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
20510 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
20520 68 65 20 70 61 72 61 6d 65 74 65 72 20 66 6f 72  he parameter for
20530 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 4e  ms shown above N
20540 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  NN is an integer
20550 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64   literal,.** and
20560 20 56 56 56 20 69 73 20 61 6e 20 61 6c 70 68 61   VVV is an alpha
20570 2d 6e 75 6d 65 72 69 63 20 70 61 72 61 6d 65 74  -numeric paramet
20580 65 72 20 6e 61 6d 65 2e 20 54 68 65 20 76 61 6c  er name. The val
20590 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
205a0 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
205b0 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
205c0 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
205d0 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
205e0 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
205f0 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
20600 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
20610 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
20620 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  re..**.** The fi
20630 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
20640 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
20650 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73  _*() routines is
20660 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69   always.** a poi
20670 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
20680 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
20690 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
206a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
206b0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
206c0 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a   variants..**.**
206d0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
206e0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
206f0 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
20700 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
20710 2e 0a 2a 2a 20 54 68 65 20 6c 65 66 74 6d 6f 73  ..** The leftmos
20720 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
20730 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
20740 31 2e 20 20 57 68 65 6e 20 74 68 65 20 73 61 6d  1.  When the sam
20750 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
20760 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
20770 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
20780 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
20790 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
207a0 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
207b0 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
207c0 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
207d0 65 2e 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78 20  e..** The index 
207e0 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
207f0 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
20800 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
20810 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
20820 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
20830 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
20840 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78 0a 2a  ed.  The index.*
20850 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
20860 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
20870 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
20880 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
20890 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
208a0 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
208b0 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
208c0 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
208d0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
208e0 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
208f0 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
20900 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75  * The third argu
20910 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
20920 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
20930 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
20940 2a 20 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  * In those routi
20950 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
20960 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
20970 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
20980 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
20990 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
209a0 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
209b0 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
209c0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
209d0 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
209e0 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
209f0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
20a00 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 49  characters..** I
20a10 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
20a20 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69  ameter is negati
20a30 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  ve, the length o
20a40 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
20a50 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
20a60 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
20a70 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
20a80 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  inator..**.** Th
20a90 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
20aa0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
20ab0 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
20ac0 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e  _bind_text(), an
20ad0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  d.** sqlite3_bin
20ae0 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20  d_text16() is a 
20af0 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
20b00 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
20b10 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
20b20 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
20b30 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
20b40 74 68 20 69 74 2e 20 49 66 20 74 68 65 20 66 69  th it. If the fi
20b50 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
20b60 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
20b70 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
20b80 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
20b90 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
20ba0 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
20bb0 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
20bc0 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
20bd0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
20be0 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
20bf0 2a 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61  * If the fifth a
20c00 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
20c10 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
20c20 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
20c30 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
20c40 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
20c50 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
20c60 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
20c70 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
20c80 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
20c90 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
20ca0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
20cb0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
20cc0 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
20cd0 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20  LOB of length N 
20ce0 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
20cf0 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20  d with zeroes.  
20d00 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
20d10 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
20d20 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
20d30 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
20d40 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77  hold its size) w
20d50 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
20d60 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
20d70 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
20d80 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
20d90 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  s placeholders f
20da0 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
20db0 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
20dc0 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
20dd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
20de0 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
20df0 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ntal BLOB I/O] r
20e00 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65  outines..** A ne
20e10 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
20e20 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
20e30 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
20e40 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
20e50 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
20e60 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
20e70 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
20e80 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  after.** [sqlite
20e90 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
20ea0 28 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74  (and its variant
20eb0 73 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  s) or [sqlite3_r
20ec0 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62  eset()] and.** b
20ed0 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73  efore [sqlite3_s
20ee0 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69  tep()]..** Bindi
20ef0 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
20f00 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
20f10 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
20f20 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64  tine..** Unbound
20f30 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
20f40 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
20f50 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ULL..**.** These
20f60 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
20f70 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
20f80 73 75 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72  success or an er
20f90 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61  ror code if.** a
20fa0 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
20fb0 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e  ng.  [SQLITE_RAN
20fc0 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
20fd0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
20fe0 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
20ff0 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c   of range.  [SQL
21000 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
21010 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
21020 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51  () fails..** [SQ
21030 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 69 67  LITE_MISUSE] mig
21040 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69  ht be returned i
21050 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
21060 20 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61   are called on a
21070 0a 2a 2a 20 76 69 72 74 75 61 6c 20 6d 61 63 68  .** virtual mach
21080 69 6e 65 20 74 68 61 74 20 69 73 20 74 68 65 20  ine that is the 
21090 77 72 6f 6e 67 20 73 74 61 74 65 20 6f 72 20 77  wrong state or w
210a0 68 69 63 68 20 68 61 73 20 61 6c 72 65 61 64 79  hich has already
210b0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e   been finalized.
210c0 0a 2a 2a 20 44 65 74 65 63 74 69 6f 6e 20 6f 66  .** Detection of
210d0 20 6d 69 73 75 73 65 20 69 73 20 75 6e 72 65 6c   misuse is unrel
210e0 69 61 62 6c 65 2e 20 20 41 70 70 6c 69 63 61 74  iable.  Applicat
210f0 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ions should not 
21100 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c  depend.** on SQL
21110 49 54 45 5f 4d 49 53 55 53 45 20 72 65 74 75 72  ITE_MISUSE retur
21120 6e 73 2e 20 20 53 51 4c 49 54 45 5f 4d 49 53 55  ns.  SQLITE_MISU
21130 53 45 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  SE is intended t
21140 6f 20 69 6e 64 69 63 61 74 65 20 61 0a 2a 2a 20  o indicate a.** 
21150 61 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e  a logic error in
21160 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
21170 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
21180 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
21190 68 74 0a 2a 2a 20 70 61 6e 69 63 20 72 61 74 68  ht.** panic rath
211a0 65 72 20 74 68 61 6e 20 72 65 74 75 72 6e 20 53  er than return S
211b0 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
211c0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
211d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
211e0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
211f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
21200 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
21210 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
21220 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
21230 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  index()]..**.** 
21240 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
21250 2a 20 7b 48 31 33 35 30 36 7d 20 54 68 65 20 5b  * {H13506} The [
21260 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
21270 6d 70 69 6c 65 72 5d 20 72 65 63 6f 67 6e 69 7a  mpiler] recogniz
21280 65 73 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65  es tokens of the
21290 20 66 6f 72 6d 73 0a 2a 2a 20 20 20 20 20 20 20   forms.**       
212a0 20 20 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20     "?", "?NNN", 
212b0 22 24 56 56 56 22 2c 20 22 3a 56 56 56 22 2c 20  "$VVV", ":VVV", 
212c0 61 6e 64 20 22 40 56 56 56 22 20 61 73 20 53 51  and "@VVV" as SQ
212d0 4c 20 70 61 72 61 6d 65 74 65 72 73 2c 0a 2a 2a  L parameters,.**
212e0 20 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20            where 
212f0 4e 4e 4e 20 69 73 20 61 6e 79 20 73 65 71 75 65  NNN is any seque
21300 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  nce of one or mo
21310 72 65 20 64 69 67 69 74 73 0a 2a 2a 20 20 20 20  re digits.**    
21320 20 20 20 20 20 20 61 6e 64 20 77 68 65 72 65 20        and where 
21330 56 56 56 20 69 73 20 61 6e 79 20 73 65 71 75 65  VVV is any seque
21340 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  nce of one or mo
21350 72 65 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 0a  re alphanumeric.
21360 2a 2a 20 20 20 20 20 20 20 20 20 20 63 68 61 72  **          char
21370 61 63 74 65 72 73 20 6f 72 20 22 3a 3a 22 20 6f  acters or "::" o
21380 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77  ptionally follow
21390 65 64 20 62 79 20 61 20 73 74 72 69 6e 67 20 63  ed by a string c
213a0 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20  ontaining.**    
213b0 20 20 20 20 20 20 6e 6f 20 73 70 61 63 65 73 20        no spaces 
213c0 61 6e 64 20 63 6f 6e 74 61 69 6e 65 64 20 77 69  and contained wi
213d0 74 68 69 6e 20 70 61 72 65 6e 74 68 65 73 65 73  thin parentheses
213e0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30 39 7d  ..**.** {H13509}
213f0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 76 61 6c   The initial val
21400 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ue of an SQL par
21410 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 2e 0a  ameter is NULL..
21420 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 32 7d 20 54  **.** {H13512} T
21430 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22  he index of an "
21440 3f 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ?" SQL parameter
21450 20 69 73 20 6f 6e 65 20 6c 61 72 67 65 72 20 74   is one larger t
21460 68 61 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  han the.**      
21470 20 20 20 20 6c 61 72 67 65 73 74 20 69 6e 64 65      largest inde
21480 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74  x of SQL paramet
21490 65 72 20 74 6f 20 74 68 65 20 6c 65 66 74 2c 20  er to the left, 
214a0 6f 72 20 31 20 69 66 0a 2a 2a 20 20 20 20 20 20  or 1 if.**      
214b0 20 20 20 20 74 68 65 20 22 3f 22 20 69 73 20 74      the "?" is t
214c0 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20  he leftmost SQL 
214d0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
214e0 20 7b 48 31 33 35 31 35 7d 20 54 68 65 20 69 6e   {H13515} The in
214f0 64 65 78 20 6f 66 20 61 6e 20 22 3f 4e 4e 4e 22  dex of an "?NNN"
21500 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
21510 73 20 74 68 65 20 69 6e 74 65 67 65 72 20 4e 4e  s the integer NN
21520 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 38  N..**.** {H13518
21530 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61  } The index of a
21540 6e 20 22 3a 56 56 56 22 2c 20 22 24 56 56 56 22  n ":VVV", "$VVV"
21550 2c 20 6f 72 20 22 40 56 56 56 22 20 53 51 4c 20  , or "@VVV" SQL 
21560 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
21570 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d           the sam
21580 65 20 61 73 20 74 68 65 20 69 6e 64 65 78 20 6f  e as the index o
21590 66 20 6c 65 66 74 6d 6f 73 74 20 6f 63 63 75 72  f leftmost occur
215a0 72 65 6e 63 65 73 20 6f 66 20 74 68 65 20 73 61  rences of the sa
215b0 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  me.**          p
215c0 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 6f 6e 65  arameter, or one
215d0 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 65 20 6c   more than the l
215e0 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 76 65  argest index ove
215f0 72 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  r all.**        
21600 20 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20    parameters to 
21610 74 68 65 20 6c 65 66 74 20 69 66 20 74 68 69 73  the left if this
21620 20 69 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   is the first oc
21630 63 75 72 72 65 6e 63 65 0a 2a 2a 20 20 20 20 20  currence.**     
21640 20 20 20 20 20 6f 66 20 74 68 69 73 20 70 61 72       of this par
21650 61 6d 65 74 65 72 2c 20 6f 72 20 31 20 69 66 20  ameter, or 1 if 
21660 74 68 69 73 20 69 73 20 74 68 65 20 6c 65 66 74  this is the left
21670 6d 6f 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  most parameter..
21680 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 31 7d 20 54  **.** {H13521} T
21690 68 65 20 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e  he [SQL statemen
216a0 74 20 63 6f 6d 70 69 6c 65 72 5d 20 66 61 69 6c  t compiler] fail
216b0 73 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54  s with an [SQLIT
216c0 45 5f 52 41 4e 47 45 5d 0a 2a 2a 20 20 20 20 20  E_RANGE].**     
216d0 20 20 20 20 20 65 72 72 6f 72 20 69 66 20 74 68       error if th
216e0 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51  e index of an SQ
216f0 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c  L parameter is l
21700 65 73 73 20 74 68 61 6e 20 31 0a 2a 2a 20 20 20  ess than 1.**   
21710 20 20 20 20 20 20 20 6f 72 20 67 72 65 61 74 65         or greate
21720 72 20 74 68 61 6e 20 74 68 65 20 63 6f 6d 70 69  r than the compi
21730 6c 65 2d 74 69 6d 65 20 53 51 4c 49 54 45 5f 4d  le-time SQLITE_M
21740 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  AX_VARIABLE_NUMB
21750 45 52 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  ER.**          p
21760 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
21770 7b 48 31 33 35 32 34 7d 20 43 61 6c 6c 73 20 74  {H13524} Calls t
21780 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
21790 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62  text | sqlite3_b
217a0 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e 2e 29 5d 0a  ind(S,N,V,...)].
217b0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 6f  **          asso
217c0 63 69 61 74 65 20 74 68 65 20 76 61 6c 75 65 20  ciate the value 
217d0 56 20 77 69 74 68 20 61 6c 6c 20 53 51 4c 20 70  V with all SQL p
217e0 61 72 61 6d 65 74 65 72 73 20 68 61 76 69 6e 67  arameters having
217f0 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
21800 69 6e 64 65 78 20 6f 66 20 4e 20 69 6e 20 74 68  index of N in th
21810 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
21820 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20  ement] S..**.** 
21830 7b 48 31 33 35 32 37 7d 20 43 61 6c 6c 73 20 74  {H13527} Calls t
21840 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
21850 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62  text | sqlite3_b
21860 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a  ind(S,N,...)].**
21870 20 20 20 20 20 20 20 20 20 20 6f 76 65 72 72 69            overri
21880 64 65 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 77  de prior calls w
21890 69 74 68 20 74 68 65 20 73 61 6d 65 20 76 61 6c  ith the same val
218a0 75 65 73 20 6f 66 20 53 20 61 6e 64 20 4e 2e 0a  ues of S and N..
218b0 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 30 7d 20 42  **.** {H13530} B
218c0 69 6e 64 69 6e 67 73 20 65 73 74 61 62 6c 69 73  indings establis
218d0 68 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  hed by [sqlite3_
218e0 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69  bind_text | sqli
218f0 74 65 33 5f 62 69 6e 64 28 53 2c 2e 2e 2e 29 5d  te3_bind(S,...)]
21900 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 65 72  .**          per
21910 73 69 73 74 20 61 63 72 6f 73 73 20 63 61 6c 6c  sist across call
21920 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
21930 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  set(S)]..**.** {
21940 48 31 33 35 33 33 7d 20 49 6e 20 63 61 6c 6c 73  H13533} In calls
21950 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
21960 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44  d_blob(S,N,V,L,D
21970 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
21980 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
21990 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20  xt(S,N,V,L,D)], 
219a0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
219b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
219c0 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20  t16(S,N,V,L,D)] 
219d0 53 51 4c 69 74 65 20 62 69 6e 64 73 20 74 68 65  SQLite binds the
219e0 20 66 69 72 73 74 20 4c 0a 2a 2a 20 20 20 20 20   first L.**     
219f0 20 20 20 20 20 62 79 74 65 73 20 6f 66 20 74 68       bytes of th
21a00 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  e BLOB or string
21a10 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56   pointed to by V
21a20 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20 20 20 20 20  , when L.**     
21a30 20 20 20 20 20 69 73 20 6e 6f 6e 2d 6e 65 67 61       is non-nega
21a40 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  tive..**.** {H13
21a50 35 33 36 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  536} In calls to
21a60 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
21a70 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20  ext(S,N,V,L,D)] 
21a80 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
21a90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
21aa0 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20  t16(S,N,V,L,D)] 
21ab0 53 51 4c 69 74 65 20 62 69 6e 64 73 20 63 68 61  SQLite binds cha
21ac0 72 61 63 74 65 72 73 0a 2a 2a 20 20 20 20 20 20  racters.**      
21ad0 20 20 20 20 66 72 6f 6d 20 56 20 74 68 72 6f 75      from V throu
21ae0 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
21af0 6f 20 63 68 61 72 61 63 74 65 72 20 77 68 65 6e  o character when
21b00 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a   L is negative..
21b10 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 39 7d 20 49  **.** {H13539} I
21b20 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
21b30 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c  te3_bind_blob(S,
21b40 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20  N,V,L,D)],.**   
21b50 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
21b60 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c  bind_text(S,N,V,
21b70 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  L,D)], or.**    
21b80 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
21b90 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56  ind_text16(S,N,V
21ba0 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73  ,L,D)] when D is
21bb0 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20   the special.** 
21bc0 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 61 6e           constan
21bd0 74 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  t [SQLITE_STATIC
21be0 5d 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  ], SQLite assume
21bf0 73 20 74 68 61 74 20 74 68 65 20 76 61 6c 75 65  s that the value
21c00 20 56 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69   V.**          i
21c10 73 20 68 65 6c 64 20 69 6e 20 73 74 61 74 69 63  s held in static
21c20 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65   unmanaged space
21c30 20 74 68 61 74 20 77 69 6c 6c 20 6e 6f 74 20 63   that will not c
21c40 68 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  hange.**        
21c50 20 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66    during the lif
21c60 65 74 69 6d 65 20 6f 66 20 74 68 65 20 62 69 6e  etime of the bin
21c70 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ding..**.** {H13
21c80 35 34 32 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  542} In calls to
21c90 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
21ca0 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c  lob(S,N,V,L,D)],
21cb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
21cc0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
21cd0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a  S,N,V,L,D)], or.
21ce0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
21cf0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
21d00 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65  (S,N,V,L,D)] whe
21d10 6e 20 44 20 69 73 20 74 68 65 20 73 70 65 63 69  n D is the speci
21d20 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  al.**          c
21d30 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f  onstant [SQLITE_
21d40 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 20  TRANSIENT], the 
21d50 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73 20 61 0a  routine makes a.
21d60 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 69 76  **          priv
21d70 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
21d80 76 61 6c 75 65 20 56 20 62 65 66 6f 72 65 20 69  value V before i
21d90 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
21da0 20 7b 48 31 33 35 34 35 7d 20 49 6e 20 63 61 6c   {H13545} In cal
21db0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
21dc0 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c  ind_blob(S,N,V,L
21dd0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
21de0 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
21df0 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  text(S,N,V,L,D)]
21e00 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
21e10 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
21e20 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
21e30 5d 20 77 68 65 6e 20 44 20 69 73 20 61 20 70 6f  ] when D is a po
21e40 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20  inter to.**     
21e50 20 20 20 20 20 61 20 66 75 6e 63 74 69 6f 6e 2c       a function,
21e60 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
21e70 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 74 6f  that function to
21e80 20 64 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20   destroy the.** 
21e90 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 56           value V
21ea0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
21eb0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65  nished using the
21ec0 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20   value V..**.** 
21ed0 7b 48 31 33 35 34 38 7d 20 49 6e 20 63 61 6c 6c  {H13548} In call
21ee0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
21ef0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 53 2c 4e 2c  nd_zeroblob(S,N,
21f00 56 2c 4c 29 5d 20 74 68 65 20 76 61 6c 75 65 20  V,L)] the value 
21f10 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  bound.**        
21f20 20 20 69 73 20 61 20 42 4c 4f 42 20 6f 66 20 4c    is a BLOB of L
21f30 20 62 79 74 65 73 2c 20 6f 72 20 61 20 7a 65 72   bytes, or a zer
21f40 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 66  o-length BLOB if
21f50 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a   L is negative..
21f60 2a 2a 0a 2a 2a 20 7b 48 31 33 35 35 31 7d 20 49  **.** {H13551} I
21f70 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
21f80 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 53  te3_bind_value(S
21f90 2c 4e 2c 56 29 5d 20 74 68 65 20 56 20 61 72 67  ,N,V)] the V arg
21fa0 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20 20 20 20  ument may.**    
21fb0 20 20 20 20 20 20 62 65 20 65 69 74 68 65 72 20        be either 
21fc0 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  a [protected sql
21fd0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
21fe0 63 74 20 6f 72 20 61 6e 0a 2a 2a 20 20 20 20 20  ct or an.**     
21ff0 20 20 20 20 20 5b 75 6e 70 72 6f 74 65 63 74 65       [unprotecte
22000 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
22010 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20   object..*/.int 
22020 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
22030 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
22040 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
22050 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
22060 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
22070 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
22080 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
22090 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
220a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
220b0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
220c0 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
220d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
220e0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
220f0 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
22100 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
22110 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
22120 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
22130 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
22140 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
22150 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
22160 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
22170 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
22180 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
22190 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
221a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
221b0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
221c0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
221d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
221e0 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
221f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
22200 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
22210 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
22220 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
22230 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
22240 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
22250 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
22260 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
22270 74 65 72 73 20 7b 48 31 33 36 30 30 7d 20 3c 48  ters {H13600} <H
22280 31 33 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  13500>.**.** Thi
22290 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
222a0 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
222b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
222c0 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
222d0 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
222e0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
222f0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
22300 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
22310 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
22320 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
22330 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
22340 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
22350 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
22360 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
22370 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
22380 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
22390 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
223a0 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
223b0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
223c0 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75  ne actually retu
223d0 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66  rns the index of
223e0 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69   the largest (ri
223f0 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61  ghtmost).** para
22400 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66  meter. For all f
22410 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e  orms except ?NNN
22420 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72  , this will corr
22430 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a  espond to the.**
22440 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75   number of uniqu
22450 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49  e parameters.  I
22460 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  f parameters of 
22470 74 68 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65  the ?NNN are use
22480 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20  d,.** there may 
22490 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c  be gaps in the l
224a0 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ist..**.** See a
224b0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
224c0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
224d0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
224e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
224f0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
22500 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
22510 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
22520 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  x()]..**.** INVA
22530 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
22540 31 33 36 30 31 7d 20 54 68 65 20 5b 73 71 6c 69  13601} The [sqli
22550 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
22560 65 72 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74  er_count(S)] int
22570 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
22580 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6c  *          the l
22590 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20  argest index of 
225a0 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65  all SQL paramete
225b0 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20  rs in the.**    
225c0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
225d0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72  statement] S, or
225e0 20 30 20 69 66 20 53 20 63 6f 6e 74 61 69 6e 73   0 if S contains
225f0 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 65   no SQL paramete
22600 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  rs..*/.int sqlit
22610 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
22620 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
22630 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
22640 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
22650 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
22660 72 20 7b 48 31 33 36 32 30 7d 20 3c 48 31 33 35  r {H13620} <H135
22670 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00>.**.** This r
22680 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
22690 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
226a0 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68  name of the n-th
226b0 0a 2a 2a 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  .** [SQL paramet
226c0 65 72 5d 20 69 6e 20 61 20 5b 70 72 65 70 61 72  er] in a [prepar
226d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
226e0 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  * SQL parameters
226f0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
22700 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
22710 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
22720 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
22730 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
22740 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
22750 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
22760 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
22770 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
22780 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
22790 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
227a0 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
227b0 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
227c0 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
227d0 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65   name..** Parame
227e0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
227f0 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
22800 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
22810 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
22820 20 61 6e 64 20 61 72 65 20 61 6c 73 6f 20 72 65   and are also re
22830 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 61 6e  ferred to as "an
22840 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
22850 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  rs"..**.** The f
22860 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
22870 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
22880 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
22890 0a 2a 2a 20 49 66 20 74 68 65 20 76 61 6c 75 65  .** If the value
228a0 20 6e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   n is out of ran
228b0 67 65 20 6f 72 20 69 66 20 74 68 65 20 6e 2d 74  ge or if the n-t
228c0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
228d0 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e  * nameless, then
228e0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
228f0 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64  d.  The returned
22900 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
22910 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e  ways in UTF-8 en
22920 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
22930 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
22940 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
22950 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
22960 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
22970 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
22980 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
22990 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
229a0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
229b0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
229c0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
229d0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
229e0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
229f0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
22a00 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
22a10 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
22a20 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
22a30 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ANTS:.**.** {H13
22a40 36 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  621} The [sqlite
22a50 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
22a60 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65  _name(S,N)] inte
22a70 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
22a80 20 20 20 20 20 20 20 20 20 20 61 20 55 54 46 2d            a UTF-
22a90 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
22aa0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
22ab0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e 0a  QL parameter in.
22ac0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
22ad0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22ae0 65 6e 74 5d 20 53 20 68 61 76 69 6e 67 20 69 6e  ent] S having in
22af0 64 65 78 20 4e 2c 20 6f 72 0a 2a 2a 20 20 20 20  dex N, or.**    
22b00 20 20 20 20 20 20 4e 55 4c 4c 20 69 66 20 74 68        NULL if th
22b10 65 72 65 20 69 73 20 6e 6f 20 53 51 4c 20 70 61  ere is no SQL pa
22b20 72 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64  rameter with ind
22b30 65 78 20 4e 20 6f 72 20 69 66 20 74 68 65 0a 2a  ex N or if the.*
22b40 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
22b50 65 74 65 72 20 77 69 74 68 20 69 6e 64 65 78 20  eter with index 
22b60 4e 20 69 73 20 61 6e 20 61 6e 6f 6e 79 6d 6f 75  N is an anonymou
22b70 73 20 70 61 72 61 6d 65 74 65 72 20 22 3f 22 2e  s parameter "?".
22b80 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
22b90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
22ba0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69  ameter_name(sqli
22bb0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
22bc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22bd0 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72  : Index Of A Par
22be0 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69  ameter With A Gi
22bf0 76 65 6e 20 4e 61 6d 65 20 7b 48 31 33 36 34 30  ven Name {H13640
22c00 7d 20 3c 48 31 33 35 30 30 3e 0a 2a 2a 0a 2a 2a  } <H13500>.**.**
22c10 20 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65   Return the inde
22c20 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
22c30 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20  meter given its 
22c40 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69 6e  name.  The.** in
22c50 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e  dex value return
22c60 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66  ed is suitable f
22c70 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65  or use as the se
22c80 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  cond.** paramete
22c90 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  r to [sqlite3_bi
22ca0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
22cb0 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72 6f  bind()].  A zero
22cc0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
22cd0 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70  if no matching p
22ce0 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e  arameter is foun
22cf0 64 2e 20 20 54 68 65 20 70 61 72 61 6d 65 74 65  d.  The paramete
22d00 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62  r.** name must b
22d10 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38  e given in UTF-8
22d20 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69   even if the ori
22d30 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a  ginal statement.
22d40 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20  ** was prepared 
22d50 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74  from UTF-16 text
22d60 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
22d70 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
22d80 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
22d90 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
22da0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
22db0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
22dc0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
22dd0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
22de0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
22df0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
22e00 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
22e10 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36  NTS:.**.** {H136
22e20 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  41} The [sqlite3
22e30 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
22e40 69 6e 64 65 78 28 53 2c 4e 29 5d 20 69 6e 74 65  index(S,N)] inte
22e50 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
22e60 20 20 20 20 20 20 20 20 20 20 74 68 65 20 69 6e            the in
22e70 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d  dex of SQL param
22e80 65 74 65 72 20 69 6e 20 74 68 65 20 5b 70 72 65  eter in the [pre
22e90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22ea0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 20 77  .**          S w
22eb0 68 6f 73 65 20 6e 61 6d 65 20 6d 61 74 63 68 65  hose name matche
22ec0 73 20 74 68 65 20 55 54 46 2d 38 20 73 74 72 69  s the UTF-8 stri
22ed0 6e 67 20 4e 2c 20 6f 72 20 30 20 69 66 20 74 68  ng N, or 0 if th
22ee0 65 72 65 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ere is.**       
22ef0 20 20 20 6e 6f 20 6d 61 74 63 68 2e 0a 2a 2f 0a     no match..*/.
22f00 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
22f10 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
22f20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
22f30 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
22f40 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
22f50 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
22f60 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
22f70 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
22f80 7b 48 31 33 36 36 30 7d 0a 2a 2a 0a 2a 2a 20 43  {H13660}.**.** C
22f90 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
22fa0 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
22fb0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
22fc0 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73  ()] does not res
22fd0 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  et.** the [sqlit
22fe0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
22ff0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70  indings] on a [p
23000 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23010 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 68 69 73 20  t]..** Use this 
23020 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74  routine to reset
23030 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
23040 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a  ters to NULL..**
23050 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
23060 2a 2a 0a 2a 2a 20 7b 48 31 33 36 36 31 7d 20 54  **.** {H13661} T
23070 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  he [sqlite3_clea
23080 72 5f 62 69 6e 64 69 6e 67 73 28 53 29 5d 20 69  r_bindings(S)] i
23090 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
230a0 61 6c 6c 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20  all SQL.**      
230b0 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 62 69      parameter bi
230c0 6e 64 69 6e 67 73 20 69 6e 20 74 68 65 20 5b 70  ndings in the [p
230d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
230e0 74 5d 20 53 20 62 61 63 6b 20 74 6f 20 4e 55 4c  t] S back to NUL
230f0 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
23100 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
23110 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
23120 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23130 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
23140 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
23150 53 65 74 20 7b 48 31 33 37 31 30 7d 20 3c 53 31  Set {H13710} <S1
23160 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75  0700>.**.** Retu
23170 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
23180 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
23190 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
231a0 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
231b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
231c0 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  t]. This routine
231d0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53   returns 0 if pS
231e0 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a  tmt is an SQL.**
231f0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
23200 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20  does not return 
23210 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c  data (for exampl
23220 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a  e an [UPDATE])..
23230 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
23240 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 31 31 7d  :.**.** {H13711}
23250 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
23260 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69  lumn_count(S)] i
23270 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
23280 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
23290 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d  *          colum
232a0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
232b0 20 73 65 74 20 67 65 6e 65 72 61 74 65 64 20 62   set generated b
232c0 79 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  y the [prepared 
232d0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a  statement] S,.**
232e0 20 20 20 20 20 20 20 20 20 20 6f 72 20 30 20 69            or 0 i
232f0 66 20 53 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e  f S does not gen
23300 65 72 61 74 65 20 61 20 72 65 73 75 6c 74 20 73  erate a result s
23310 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  et..*/.int sqlit
23320 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
23330 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
23340 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
23350 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
23360 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
23370 53 65 74 20 7b 48 31 33 37 32 30 7d 20 3c 53 31  Set {H13720} <S1
23380 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0700>.**.** Thes
23390 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
233a0 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
233b0 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
233c0 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
233d0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
233e0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
233f0 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71  atement.  The sq
23400 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
23410 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
23420 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
23430 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
23440 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
23450 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
23460 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
23470 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
23480 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
23490 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
234a0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68  F-16 string.  Th
234b0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
234c0 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72  r is the [prepar
234d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
234e0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
234f0 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
23500 61 74 65 6d 65 6e 74 2e 20 54 68 65 20 73 65 63  atement. The sec
23510 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
23520 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
23530 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74  umber.  The left
23540 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
23550 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54  umber 0..**.** T
23560 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
23570 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
23580 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
23590 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
235a0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20  tatement].** is 
235b0 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
235c0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
235d0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  ] or until the n
235e0 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
235f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
23600 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
23610 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
23620 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
23630 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c  mn..**.** If sql
23640 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
23650 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
23660 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
23670 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
23680 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
23690 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
236a0 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
236b0 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
236c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
236d0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
236e0 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
236f0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
23700 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
23710 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
23720 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
23730 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
23740 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
23750 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
23760 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
23770 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
23780 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
23790 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
237a0 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
237b0 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
237c0 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a  o the next..**.*
237d0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
237e0 0a 2a 2a 20 7b 48 31 33 37 32 31 7d 20 41 20 73  .** {H13721} A s
237f0 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
23800 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c  tion of the [sql
23810 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
23820 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  (S,N)].**       
23830 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74     interface ret
23840 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  urns the name of
23850 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
23860 28 77 68 65 72 65 20 30 20 69 73 0a 2a 2a 20 20  (where 0 is.**  
23870 20 20 20 20 20 20 20 20 74 68 65 20 6c 65 66 74          the left
23880 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72  most column) for
23890 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
238a0 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
238b0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
238c0 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 20 7a  tement] S as a z
238d0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
238e0 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
238f0 2a 2a 20 7b 48 31 33 37 32 33 7d 20 41 20 73 75  ** {H13723} A su
23900 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
23910 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
23920 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
23930 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20  6(S,N)].**      
23940 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65      interface re
23950 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f  turns the name o
23960 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
23970 20 28 77 68 65 72 65 20 30 20 69 73 0a 2a 2a 20   (where 0 is.** 
23980 20 20 20 20 20 20 20 20 20 74 68 65 20 6c 65 66           the lef
23990 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f  tmost column) fo
239a0 72 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  r the result set
239b0 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
239c0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
239d0 61 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 20  atement] S as a 
239e0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
239f0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
23a00 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 68 65            in the
23a10 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
23a20 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32  er..**.** {H1372
23a30 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
23a40 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61  column_name()] a
23a50 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
23a60 6d 6e 5f 6e 61 6d 65 31 36 28 29 5d 0a 2a 2a 20  mn_name16()].** 
23a70 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
23a80 63 65 73 20 72 65 74 75 72 6e 20 61 20 4e 55 4c  ces return a NUL
23a90 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 74 68 65  L pointer if the
23aa0 79 20 61 72 65 20 75 6e 61 62 6c 65 20 74 6f 0a  y are unable to.
23ab0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f  **          allo
23ac0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68  cate memory to h
23ad0 6f 6c 64 20 74 68 65 69 72 20 6e 6f 72 6d 61 6c  old their normal
23ae0 20 72 65 74 75 72 6e 20 73 74 72 69 6e 67 73 2e   return strings.
23af0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 35 7d 20  .**.** {H13725} 
23b00 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  If the N paramet
23b10 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
23b20 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d  olumn_name(S,N)]
23b30 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
23b40 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
23b50 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 73 20  name16(S,N)] is 
23b60 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
23b70 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  en the.**       
23b80 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65     interfaces re
23b90 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  turn a NULL poin
23ba0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  ter..**.** {H137
23bb0 32 36 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20  26} The strings 
23bc0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
23bd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
23be0 28 53 2c 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  (S,N)] and.**   
23bf0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
23c00 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c  column_name16(S,
23c10 4e 29 5d 20 61 72 65 20 76 61 6c 69 64 20 75 6e  N)] are valid un
23c20 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20  til the next.** 
23c30 20 20 20 20 20 20 20 20 20 63 61 6c 6c 20 74 6f           call to
23c40 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 20   either routine 
23c50 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 53 20  with the same S 
23c60 61 6e 64 20 4e 20 70 61 72 61 6d 65 74 65 72 73  and N parameters
23c70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
23c80 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66  until [sqlite3_f
23c90 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63  inalize(S)] is c
23ca0 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  alled..**.** {H1
23cb0 33 37 32 37 7d 20 57 68 65 6e 20 61 20 72 65 73  3727} When a res
23cc0 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20  ult column of a 
23cd0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
23ce0 6e 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20  nt contains.**  
23cf0 20 20 20 20 20 20 20 20 61 6e 20 41 53 20 63 6c          an AS cl
23d00 61 75 73 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f  ause, the name o
23d10 66 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  f that column is
23d20 20 74 68 65 20 69 64 65 6e 74 69 66 69 65 72 0a   the identifier.
23d30 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74  **          to t
23d40 68 65 20 72 69 67 68 74 20 6f 66 20 74 68 65 20  he right of the 
23d50 41 53 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63  AS keyword..*/.c
23d60 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
23d70 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
23d80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
23d90 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
23da0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
23db0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
23dc0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
23dd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23de0 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
23df0 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
23e00 20 7b 48 31 33 37 34 30 7d 20 3c 53 31 30 37 30   {H13740} <S1070
23e10 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
23e20 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
23e30 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
23e40 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e  mine what column
23e50 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c   of what.** tabl
23e60 65 20 69 6e 20 77 68 69 63 68 20 64 61 74 61 62  e in which datab
23e70 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20  ase a result of 
23e80 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
23e90 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e  ment comes from.
23ea0 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
23eb0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
23ec0 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
23ed0 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
23ee0 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
23ef0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
23f00 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74  tring.  The _dat
23f10 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
23f20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
23f30 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
23f40 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
23f50 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
23f60 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
23f70 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
23f80 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
23f90 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
23fa0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
23fb0 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
23fc0 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  il the [prepared
23fd0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
23fe0 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e  estroyed.** usin
23ff0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
24000 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
24010 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
24020 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
24030 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
24040 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
24050 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  ng..**.** The na
24060 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
24070 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
24080 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
24090 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
240a0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
240b0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lumn..**.** The 
240c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
240d0 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  o the following 
240e0 63 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70  calls is a [prep
240f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
24100 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
24110 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
24120 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
24130 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
24140 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
24150 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
24160 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
24170 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
24180 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
24190 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
241a0 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
241b0 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
241c0 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
241d0 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
241e0 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
241f0 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
24200 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
24210 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65  rn.** NULL.  The
24220 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
24230 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
24240 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
24250 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
24260 2a 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72  * occurs.  Other
24270 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
24280 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
24290 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
242a0 61 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e  ase, table.** an
242b0 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  d column that qu
242c0 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
242d0 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
242e0 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77  from..**.** As w
242f0 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
24300 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
24310 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 20   postfixed with 
24320 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
24330 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
24340 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72  rings, the other
24350 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
24360 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a  n UTF-8. {END}.*
24370 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20  *.** These APIs 
24380 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
24390 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
243a0 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
243b0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
243c0 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
243d0 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
243e0 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
243f0 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
24400 7b 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74  {A13751}.** If t
24410 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
24420 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
24430 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
24440 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
24450 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
24460 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
24470 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
24480 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
24490 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
244a0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
244b0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
244c0 0a 2a 2a 20 7b 48 31 33 37 34 31 7d 20 54 68 65  .** {H13741} The
244d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
244e0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 53  _database_name(S
244f0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
24500 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
24510 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
24520 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
24530 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
24540 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 77 68  database from wh
24550 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ich the.**      
24560 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63      Nth result c
24570 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72  olumn of the [pr
24580 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24590 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65 64  ] S is extracted
245a0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
245b0 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68   NULL if the Nth
245c0 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
245d0 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73  a general expres
245e0 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  sion.**         
245f0 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
24600 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
24610 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61   to store the na
24620 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34  me..**.** {H1374
24630 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
24640 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
24650 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74  name16(S,N)] int
24660 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
24670 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
24680 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74    the UTF-16 nat
24690 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a  ive byte order z
246a0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
246b0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
246c0 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ase.**          
246d0 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e  from which the N
246e0 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
246f0 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   of the [prepare
24700 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
24710 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78  s.**          ex
24720 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
24730 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
24740 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e  mn of S is a gen
24750 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a  eral expression.
24760 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
24770 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
24780 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73  cate memory to s
24790 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
247a0 2a 0a 2a 2a 20 7b 48 31 33 37 34 33 7d 20 54 68  *.** {H13743} Th
247b0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
247c0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e  n_table_name(S,N
247d0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
247e0 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
247f0 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d          the UTF-
24800 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
24810 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61  d name of the ta
24820 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74  ble from which t
24830 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
24840 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
24850 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   of the [prepare
24860 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
24870 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20  s extracted,.** 
24880 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c           or NULL
24890 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
248a0 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e  mn of S is a gen
248b0 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a  eral expression.
248c0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
248d0 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
248e0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73  cate memory to s
248f0 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
24900 2a 0a 2a 2a 20 7b 48 31 33 37 34 34 7d 20 54 68  *.** {H13744} Th
24910 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
24920 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 53  n_table_name16(S
24930 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
24940 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
24950 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
24960 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
24970 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d   order zero-term
24980 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
24990 68 65 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20  he table.**     
249a0 20 20 20 20 20 66 72 6f 6d 20 77 68 69 63 68 20       from which 
249b0 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
249c0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72  olumn of the [pr
249d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
249e0 5d 20 53 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ] S is.**       
249f0 20 20 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72     extracted, or
24a00 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68   NULL if the Nth
24a10 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
24a20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73  a general expres
24a30 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  sion.**         
24a40 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
24a50 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
24a60 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61   to store the na
24a70 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34  me..**.** {H1374
24a80 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
24a90 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
24aa0 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  me(S,N)] interfa
24ab0 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
24ac0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
24ad0 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  e UTF-8 zero-ter
24ae0 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20  minated name of 
24af0 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
24b00 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a   from which the.
24b10 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
24b20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
24b30 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
24b40 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65  tatement] S is e
24b50 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20  xtracted,.**    
24b60 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66        or NULL if
24b70 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
24b80 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61  of S is a genera
24b90 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  l expression.** 
24ba0 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75           or if u
24bb0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
24bc0 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72  e memory to stor
24bd0 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a  e the name..**.*
24be0 2a 20 7b 48 31 33 37 34 36 7d 20 54 68 65 20 5b  * {H13746} The [
24bf0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
24c00 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e  rigin_name16(S,N
24c10 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
24c20 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
24c30 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d          the UTF-
24c40 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
24c50 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  rder zero-termin
24c60 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65  ated name of the
24c70 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20   table.**       
24c80 20 20 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77     column from w
24c90 68 69 63 68 20 74 68 65 20 4e 74 68 20 72 65 73  hich the Nth res
24ca0 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ult column of th
24cb0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
24cc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24cd0 74 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65  t] S is extracte
24ce0 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
24cf0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  e Nth column.** 
24d00 20 20 20 20 20 20 20 20 20 6f 66 20 53 20 69 73           of S is
24d10 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65   a general expre
24d20 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62  ssion or if unab
24d30 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
24d40 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20  emory.**        
24d50 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e    to store the n
24d60 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  ame..**.** {H137
24d70 34 38 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76  48} The return v
24d80 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20  alues from.**   
24d90 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
24da0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
24db0 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
24dc0 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
24dd0 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  s].**          a
24de0 72 65 20 76 61 6c 69 64 20 66 6f 72 20 74 68 65  re valid for the
24df0 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65   lifetime of the
24e00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24e10 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ment].**        
24e20 20 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 65    or until the e
24e30 6e 63 6f 64 69 6e 67 20 69 73 20 63 68 61 6e 67  ncoding is chang
24e40 65 64 20 62 79 20 61 6e 6f 74 68 65 72 20 6d 65  ed by another me
24e50 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20  tadata.**       
24e60 20 20 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c     interface cal
24e70 6c 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 70  l for the same p
24e80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24e90 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a  t and column..**
24ea0 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a  .** ASSUMPTIONS:
24eb0 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 20  .**.** {A13751} 
24ec0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
24ed0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
24ee0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20  or more.**      
24ef0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
24f00 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
24f10 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
24f20 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
24f30 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20  **          for 
24f40 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
24f50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
24f60 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
24f70 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74 20 74  **          at t
24f80 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
24f90 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
24fa0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
24fb0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
24fc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
24fd0 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
24fe0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
24ff0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
25000 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
25010 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
25020 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
25030 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
25040 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
25050 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
25060 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
25070 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
25080 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
25090 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
250a0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
250b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
250c0 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
250d0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
250e0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
250f0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
25100 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
25110 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
25120 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
25130 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
25140 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b  A Query Result {
25150 48 31 33 37 36 30 7d 20 3c 53 31 30 37 30 30 3e  H13760} <S10700>
25160 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
25170 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
25180 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25190 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
251a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
251b0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
251c0 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
251d0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
251e0 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
251f0 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
25200 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
25210 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
25220 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
25230 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
25240 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
25250 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
25260 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
25270 6e 65 64 2e 20 20 49 66 20 74 68 65 20 4e 74 68  ned.  If the Nth
25280 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
25290 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
252a0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
252b0 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
252c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
252d0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54  s returned..** T
252e0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
252f0 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46  ng is always UTF
25300 2d 38 20 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44  -8 encoded. {END
25310 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  }.**.** For exam
25320 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
25330 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
25340 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
25350 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
25360 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
25370 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
25380 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
25390 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
253a0 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
253b0 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
253c0 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
253d0 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
253e0 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
253f0 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
25400 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
25410 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
25420 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
25430 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
25440 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20  n (i==0)..**.** 
25450 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
25460 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
25470 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65  ing.  So just be
25480 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a  cause a column.*
25490 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f  * is declared to
254a0 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69   contain a parti
254b0 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20  cular type does 
254c0 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68  not mean that th
254d0 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64  e.** data stored
254e0 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   in that column 
254f0 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72  is of the declar
25500 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65  ed type.  SQLite
25510 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20   is.** strongly 
25520 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74  typed, but the t
25530 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63  yping is dynamic
25540 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79   not static.  Ty
25550 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
25560 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
25570 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
25580 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
25590 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
255a0 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
255b0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
255c0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36  TS:.**.** {H1376
255d0 31 7d 20 20 41 20 73 75 63 63 65 73 73 66 75 6c  1}  A successful
255e0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
255f0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
25600 65 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20  e(S,N)] returns 
25610 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 7a  a.**           z
25620 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
25630 54 46 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e 74  TF-8 string cont
25640 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63 6c 61  aining the decla
25650 72 65 64 20 64 61 74 61 74 79 70 65 0a 2a 2a 20  red datatype.** 
25660 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
25670 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
25680 61 74 20 61 70 70 65 61 72 73 20 61 73 20 74 68  at appears as th
25690 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75  e Nth column (nu
256a0 6d 62 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20  mbered.**       
256b0 20 20 20 20 66 72 6f 6d 20 30 29 20 6f 66 20 74      from 0) of t
256c0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f  he result set to
256d0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
256e0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a  tatement] S..**.
256f0 2a 2a 20 7b 48 31 33 37 36 32 7d 20 20 41 20 73  ** {H13762}  A s
25700 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
25710 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
25720 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e  n_decltype16(S,N
25730 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  )].**           
25740 72 65 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74  returns a zero-t
25750 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36  erminated UTF-16
25760 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
25770 65 72 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20  er string.**    
25780 20 20 20 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e         containin
25790 67 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 64  g the declared d
257a0 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 74  atatype of the t
257b0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
257c0 20 61 70 70 65 61 72 73 0a 2a 2a 20 20 20 20 20   appears.**     
257d0 20 20 20 20 20 20 61 73 20 74 68 65 20 4e 74 68        as the Nth
257e0 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65   column (numbere
257f0 64 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65  d from 0) of the
25800 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74   result set to t
25810 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  he.**           
25820 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25830 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ent] S..**.** {H
25840 31 33 37 36 33 7d 20 20 49 66 20 4e 20 69 73 20  13763}  If N is 
25850 6c 65 73 73 20 74 68 61 6e 20 30 20 6f 72 20 4e  less than 0 or N
25860 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
25870 20 6f 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20   or equal to.** 
25880 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6e 75            the nu
25890 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
258a0 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
258b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a   statement] S,.*
258c0 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  *           or i
258d0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
258e0 20 6f 66 20 53 20 69 73 20 61 6e 20 65 78 70 72   of S is an expr
258f0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
25900 72 79 20 72 61 74 68 65 72 0a 2a 2a 20 20 20 20  ry rather.**    
25910 20 20 20 20 20 20 20 74 68 61 6e 20 61 20 74 61         than a ta
25920 62 6c 65 20 63 6f 6c 75 6d 6e 2c 20 6f 72 20 69  ble column, or i
25930 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
25940 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a  ation failure.**
25950 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72             occur
25960 73 20 64 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e  s during encodin
25970 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74  g conversions, t
25980 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
25990 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
259a0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
259b0 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20  pe(S,N)] or.**  
259c0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
259d0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
259e0 65 31 36 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e  e16(S,N)] return
259f0 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20   NULL..*/.const 
25a00 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
25a10 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
25a20 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
25a30 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
25a40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
25a50 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
25a60 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
25a70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
25a80 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
25a90 74 65 6d 65 6e 74 20 7b 48 31 33 32 30 30 7d 20  tement {H13200} 
25aa0 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41  <S10000>.**.** A
25ab0 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64  fter a [prepared
25ac0 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20   statement] has 
25ad0 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73  been prepared us
25ae0 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73  ing either.** [s
25af0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
25b00 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
25b10 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
25b20 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c   or one of the l
25b30 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
25b40 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
25b50 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  pare()] or [sqli
25b60 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
25b70 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a  , this function.
25b80 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ** must be calle
25b90 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
25ba0 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20  mes to evaluate 
25bb0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  the statement..*
25bc0 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
25bd0 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72   of the behavior
25be0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
25bf0 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65  step() interface
25c00 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68   depend.** on wh
25c10 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d  ether the statem
25c20 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64  ent was prepared
25c30 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72   using the newer
25c40 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a   "v2" interface.
25c50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
25c60 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
25c70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
25c80 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c  _v2()] or the ol
25c90 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  der legacy.** in
25ca0 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33  terface [sqlite3
25cb0 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
25cc0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
25cd0 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20  16()].  The use 
25ce0 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76  of the.** new "v
25cf0 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
25d00 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
25d10 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
25d20 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a   but the legacy.
25d30 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  ** interface wil
25d40 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  l continue to be
25d50 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a   supported..**.*
25d60 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  * In the legacy 
25d70 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
25d80 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
25d90 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
25da0 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
25db0 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
25dc0 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
25dd0 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
25de0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
25df0 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69   With the "v2" i
25e00 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
25e10 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
25e20 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
25e30 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
25e40 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
25e50 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
25e60 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  l..**.** [SQLITE
25e70 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
25e80 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
25e90 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
25ea0 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
25eb0 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
25ec0 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
25ed0 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68   its job.  If th
25ee0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
25ef0 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
25f00 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
25f10 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
25f20 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
25f30 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
25f40 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
25f50 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
25f60 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
25f70 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
25f80 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69  ithin a.** expli
25f90 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
25fa0 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
25fb0 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
25fc0 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
25fd0 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
25fe0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  *.** [SQLITE_DON
25ff0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
26000 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
26010 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
26020 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
26030 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
26040 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
26050 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
26060 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
26070 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
26080 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
26090 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
260a0 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
260b0 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
260c0 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
260d0 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
260e0 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
260f0 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
26100 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
26110 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
26120 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
26130 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
26140 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
26150 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
26160 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
26170 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
26180 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
26190 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
261a0 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
261b0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
261c0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
261d0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
261e0 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
261f0 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
26200 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ta..**.** [SQLIT
26210 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
26220 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
26230 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
26240 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
26250 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
26260 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
26270 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
26280 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
26290 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
262a0 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
262b0 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
262c0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
262d0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
262e0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
262f0 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
26300 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
26310 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
26320 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
26330 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
26340 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
26350 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
26360 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
26370 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
26380 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
26390 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
263a0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
263b0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20  statement].  In 
263c0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
263d0 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
263e0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
263f0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
26400 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
26410 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
26420 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
26430 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
26440 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
26450 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
26460 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
26470 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
26480 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
26490 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
264a0 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
264b0 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
264c0 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
264d0 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
264e0 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
264f0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
26500 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
26510 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
26520 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
26530 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
26540 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
26550 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
26560 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
26570 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
26580 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
26590 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
265a0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79  ..**.** <b>Goofy
265b0 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
265c0 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67  :</b> In the leg
265d0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
265e0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
265f0 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20  ).** API always 
26600 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69  returns a generi
26610 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53  c error code, [S
26620 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f  QLITE_ERROR], fo
26630 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65  llowing any.** e
26640 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20  rror other than 
26650 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e  [SQLITE_BUSY] an
26660 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  d [SQLITE_MISUSE
26670 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c  ].  You must cal
26680 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  l.** [sqlite3_re
26690 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
266a0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
266b0 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
266c0 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70  one of the.** sp
266d0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
266e0 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72  des] that better
266f0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
26700 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69  rror..** We admi
26710 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61  t that this is a
26720 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20   goofy design.  
26730 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20  The problem has 
26740 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69  been fixed.** wi
26750 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
26760 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70  rface.  If you p
26770 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f  repare all of yo
26780 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ur SQL statement
26790 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65  s.** using eithe
267a0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
267b0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
267c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
267d0 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20  2()] instead.** 
267e0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  of the legacy [s
267f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
26800 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
26810 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65  repare16()] inte
26820 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20  rfaces,.** then 
26830 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
26840 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
26850 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
26860 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
26870 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
26880 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22   use of the "v2"
26890 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
268a0 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
268b0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
268c0 2a 2a 20 7b 48 31 33 32 30 32 7d 20 20 49 66 20  ** {H13202}  If 
268d0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
268e0 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 72 65  atement] S is re
268f0 61 64 79 20 74 6f 20 62 65 20 72 75 6e 2c 20 74  ady to be run, t
26900 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
26910 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
26920 29 5d 20 61 64 76 61 6e 63 65 73 20 74 68 61 74  )] advances that
26930 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
26940 65 6e 74 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20  ent until.**    
26950 20 20 20 20 20 20 20 63 6f 6d 70 6c 65 74 69 6f         completio
26960 6e 20 6f 72 20 75 6e 74 69 6c 20 69 74 20 69 73  n or until it is
26970 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e   ready to return
26980 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20   another row of 
26990 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
269a0 20 72 65 73 75 6c 74 20 73 65 74 2c 20 6f 72 20   result set, or 
269b0 75 6e 74 69 6c 20 61 6e 20 5b 73 71 6c 69 74 65  until an [sqlite
269c0 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e  3_interrupt | in
269d0 74 65 72 72 75 70 74 5d 0a 2a 2a 20 20 20 20 20  terrupt].**     
269e0 20 20 20 20 20 20 6f 72 20 61 20 72 75 6e 2d 74        or a run-t
269f0 69 6d 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ime error occurs
26a00 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 34 7d  ..**.** {H15304}
26a10 20 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f    When a call to
26a20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
26a30 29 5d 20 63 61 75 73 65 73 20 74 68 65 20 5b 70  )] causes the [p
26a40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26a50 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  t].**           
26a60 53 20 74 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70  S to run to comp
26a70 6c 65 74 69 6f 6e 2c 20 74 68 65 20 66 75 6e 63  letion, the func
26a80 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51  tion returns [SQ
26a90 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a  LITE_DONE]..**.*
26aa0 2a 20 7b 48 31 35 33 30 36 7d 20 20 57 68 65 6e  * {H15306}  When
26ab0 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
26ac0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 73 74 6f  te3_step(S)] sto
26ad0 70 73 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ps because it is
26ae0 20 72 65 61 64 79 20 74 6f 0a 2a 2a 20 20 20 20   ready to.**    
26af0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 61 6e         return an
26b00 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65  other row of the
26b10 20 72 65 73 75 6c 74 20 73 65 74 2c 20 69 74 20   result set, it 
26b20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
26b30 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ROW]..**.** {H15
26b40 33 30 38 7d 20 20 49 66 20 61 20 63 61 6c 6c 20  308}  If a call 
26b50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
26b60 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20  (S)] encounters 
26b70 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  an.**           
26b80 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
26b90 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 20  pt | interrupt] 
26ba0 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  or a run-time er
26bb0 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ror,.**         
26bc0 20 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20    it returns an 
26bd0 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f  appropriate erro
26be0 72 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 6e  r code that is n
26bf0 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20  ot one of.**    
26c00 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f         [SQLITE_O
26c10 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  K], [SQLITE_ROW]
26c20 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  , or [SQLITE_DON
26c30 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 31  E]..**.** {H1531
26c40 30 7d 20 20 49 66 20 61 6e 20 5b 73 71 6c 69 74  0}  If an [sqlit
26c50 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69  e3_interrupt | i
26c60 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61 20 72  nterrupt] or a r
26c70 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 0a 2a 2a  un-time error.**
26c80 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72             occur
26c90 73 20 64 75 72 69 6e 67 20 61 20 63 61 6c 6c 20  s during a call 
26ca0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
26cb0 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  (S)].**         
26cc0 20 20 66 6f 72 20 61 20 5b 70 72 65 70 61 72 65    for a [prepare
26cd0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 63  d statement] S c
26ce0 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
26cf0 20 20 20 20 20 20 20 20 20 20 6c 65 67 61 63 79            legacy
26d00 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
26d10 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
26d20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  or.**           
26d30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26d40 31 36 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  16()], then the 
26d50 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
26d60 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
26d70 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52       [SQLITE_ERR
26d80 4f 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53  OR], [SQLITE_BUS
26d90 59 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  Y], or [SQLITE_M
26da0 49 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ISUSE]..*/.int s
26db0 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
26dc0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
26dd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
26de0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
26df0 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b  n a result set {
26e00 48 31 33 37 37 30 7d 20 3c 53 31 30 37 30 30 3e  H13770} <S10700>
26e10 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74  .**.** Returns t
26e20 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c  he number of val
26e30 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65  ues in the curre
26e40 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
26e50 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  sult set..**.** 
26e60 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
26e70 2a 20 7b 48 31 33 37 37 31 7d 20 20 41 66 74 65  * {H13771}  Afte
26e80 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  r a call to [sql
26e90 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 74 68  ite3_step(S)] th
26ea0 61 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  at returns [SQLI
26eb0 54 45 5f 52 4f 57 5d 2c 0a 2a 2a 20 20 20 20 20  TE_ROW],.**     
26ec0 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74        the [sqlit
26ed0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29  e3_data_count(S)
26ee0 5d 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72  ] routine will r
26ef0 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 76  eturn the same v
26f00 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  alue.**         
26f10 20 20 61 73 20 74 68 65 20 5b 73 71 6c 69 74 65    as the [sqlite
26f20 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53  3_column_count(S
26f30 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  )] function..**.
26f40 2a 2a 20 7b 48 31 33 37 37 32 7d 20 20 41 66 74  ** {H13772}  Aft
26f50 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
26f60 28 53 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  (S)] has returne
26f70 64 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  d any value othe
26f80 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20  r than.**       
26f90 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d      [SQLITE_ROW]
26fa0 20 6f 72 20 62 65 66 6f 72 65 20 5b 73 71 6c 69   or before [sqli
26fb0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
26fc0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20   been called on 
26fd0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
26fe0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26ff0 6d 65 6e 74 5d 20 66 6f 72 20 74 68 65 20 66 69  ment] for the fi
27000 72 73 74 20 74 69 6d 65 20 73 69 6e 63 65 20 69  rst time since i
27010 74 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20  t was.**        
27020 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
27030 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
27040 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
27050 74 20 7c 20 72 65 73 65 74 5d 2c 0a 2a 2a 20 20  t | reset],.**  
27060 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71           the [sq
27070 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
27080 28 53 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  (S)] routine ret
27090 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e  urns zero..*/.in
270a0 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  t sqlite3_data_c
270b0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
270c0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
270d0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64  * CAPI3REF: Fund
270e0 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65  amental Datatype
270f0 73 20 7b 48 31 30 32 36 35 7d 0a 2a 2a 20 4b 45  s {H10265}.** KE
27100 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
27110 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36  EXT.**.** {H1026
27120 36 7d 20 45 76 65 72 79 20 76 61 6c 75 65 20 69  6} Every value i
27130 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65  n SQLite has one
27140 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65   of five fundame
27150 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a  ntal datatypes:.
27160 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
27170 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  i> 64-bit signed
27180 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e   integer.** <li>
27190 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f   64-bit IEEE flo
271a0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
271b0 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e  er.** <li> strin
271c0 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a  g.** <li> BLOB.*
271d0 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c  * <li> NULL.** <
271e0 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  /ul> {END}.**.**
271f0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
27200 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
27210 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
27220 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
27230 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
27240 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
27250 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
27260 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
27270 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
27280 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
27290 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
272a0 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
272b0 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
272c0 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
272d0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
272e0 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
272f0 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
27300 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
27310 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27320 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
27330 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
27340 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
27350 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
27360 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
27370 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
27380 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
27390 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
273a0 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
273b0 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
273c0 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
273d0 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
273e0 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
273f0 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
27400 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 20 7b  s From A Query {
27410 48 31 33 38 30 30 7d 20 3c 53 31 30 37 30 30 3e  H13800} <S10700>
27420 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
27430 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
27440 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  ctions}.**.** Th
27450 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ese routines for
27460 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65  m the "result se
27470 74 20 71 75 65 72 79 22 20 69 6e 74 65 72 66 61  t query" interfa
27480 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ce..**.** These 
27490 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
274a0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
274b0 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
274c0 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
274d0 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
274e0 66 20 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65  f a query.  In e
274f0 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69  very case the fi
27500 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
27510 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
27520 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
27530 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
27540 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64   being evaluated
27550 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
27560 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tmt*].** that wa
27570 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
27580 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
27590 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
275a0 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a   its variants).*
275b0 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  * and the second
275c0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
275d0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
275e0 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69  lumn for which i
275f0 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68  nformation.** sh
27600 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
27610 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  .  The leftmost 
27620 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
27630 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65  sult set has the
27640 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20   index 0..**.** 
27650 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
27660 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75  ment does not cu
27670 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
27680 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
27690 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   if the.** colum
276a0 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
276b0 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
276c0 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
276d0 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
276e0 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
276f0 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
27700 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
27710 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
27720 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
27730 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
27740 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
27750 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
27760 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
27770 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65  finalize()] have
27780 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62   been called sub
27790 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66  sequently..** If
277a0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
277b0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
277c0 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
277d0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
277e0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
277f0 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73  e()] or after [s
27800 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
27810 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73  as returned.** s
27820 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
27830 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
27840 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
27850 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
27860 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  If [sqlite3_step
27870 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
27880 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
27890 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
278a0 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66  .** are called f
278b0 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20  rom a different 
278c0 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79  thread while any
278d0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
278e0 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e  es.** are pendin
278f0 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  g, then the resu
27900 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
27910 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
27920 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
27930 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
27940 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
27950 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
27960 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
27970 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
27980 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
27990 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54  esult column.  T
279a0 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
279b0 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
279c0 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
279d0 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
279e0 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
279f0 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
27a00 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
27a10 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
27a20 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
27a30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
27a40 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
27a50 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
27a60 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
27a70 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
27a80 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
27a90 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
27aa0 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
27ab0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
27ac0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
27ad0 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
27ae0 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
27af0 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
27b00 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
27b10 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
27b20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
27b30 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
27b40 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
27b50 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  sion..**.** If t
27b60 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
27b70 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
27b80 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
27b90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
27ba0 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  s().** routine r
27bb0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
27bc0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
27bd0 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
27be0 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  g..** If the res
27bf0 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
27c00 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
27c10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
27c20 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
27c30 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
27c40 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
27c50 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
27c60 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20  of bytes..** If 
27c70 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
27c80 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
27c90 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
27ca0 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a  n_bytes() uses.*
27cb0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
27cc0 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
27cd0 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
27ce0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61  a UTF-8 string a
27cf0 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
27d00 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
27d10 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
27d20 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72  ..** The value r
27d30 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
27d40 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
27d50 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20  o terminator at 
27d60 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
27d70 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 63  e string.  For c
27d80 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
27d90 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68  e returned is th
27da0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
27db0 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
27dc0 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
27dd0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
27de0 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20  ..**.** Strings 
27df0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
27e00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
27e10 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
27e20 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
27e30 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72  * even empty str
27e40 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
27e50 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64   zero terminated
27e60 2e 20 20 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a  .  The return.**
27e70 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
27e80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
27e90 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
27ea0 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 61  gth BLOB is an a
27eb0 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e  rbitrary.** poin
27ec0 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76  ter, possibly ev
27ed0 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
27ee0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
27ef0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
27f00 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73  s16() routine is
27f10 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69   similar to sqli
27f20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
27f30 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73  ().** but leaves
27f40 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55   the result in U
27f50 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20  TF-16 in native 
27f60 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65  byte order inste
27f70 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20  ad of UTF-8..** 
27f80 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  The zero termina
27f90 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75  tor is not inclu
27fa0 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e  ded in this coun
27fb0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a  t..**.** The obj
27fc0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
27fd0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
27fe0 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
27ff0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
28000 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
28010 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74  ject.  An unprot
28020 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
28030 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61  lue object.** ma
28040 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
28050 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  ith [sqlite3_bin
28060 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
28070 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
28080 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
28090 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
280a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
280b0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
280c0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
280d0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
280e0 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
280f0 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
28100 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
28110 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
28120 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
28130 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
28140 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
28150 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
28160 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74  bytes()], then t
28170 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
28180 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
28190 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
281a0 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
281b0 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
281c0 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
281d0 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
281e0 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  if the internal 
281f0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69  representation i
28200 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65  s FLOAT and a te
28210 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  xt result.** is 
28220 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69  requested, [sqli
28230 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
28240 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
28250 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68  ly to perform th
28260 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e.** conversion 
28270 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
28280 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
28290 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
282a0 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
282b0 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
282c0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
282d0 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
282e0 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
282f0 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
28300 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
28310 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
28320 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
28330 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
28340 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
28350 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
28360 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
28370 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
28380 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
28390 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
283a0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
283b0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
283c0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
283d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
283e0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
283f0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
28400 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
28410 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
28420 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
28430 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
28440 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
28450 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
28460 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
28470 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
28480 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
28490 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
284a0 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
284b0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
284c0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
284d0 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
284e0 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
284f0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
28500 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
28510 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
28520 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67  m float to integ
28530 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
28540 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
28550 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
28560 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
28570 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
28580 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
28590 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
285a0 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d  > Same as FLOAT-
285b0 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
285c0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
285d0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55  INTEGER   <td> U
285e0 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
285f0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
28600 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
28610 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a  d> Use atof().**
28620 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
28630 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
28640 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
28650 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
28660 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
28670 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
28680 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
28690 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
286a0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
286b0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
286c0 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
286d0 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66  XT then use atof
286e0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
286f0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
28700 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
28710 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
28720 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
28730 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
28740 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
28750 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d  he table above m
28760 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74  akes reference t
28770 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  o standard C lib
28780 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61  rary functions a
28790 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f  toi().** and ato
287a0 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65  f().  SQLite doe
287b0 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65  s not really use
287c0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
287d0 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a  .  It has its.**
287e0 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20   own equivalent 
287f0 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65  internal routine
28800 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61  s.  The atoi() a
28810 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20  nd atof() names 
28820 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74  are.** used in t
28830 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65  he table for bre
28840 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65  vity and because
28850 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69   they are famili
28860 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20  ar to most.** C 
28870 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a  programmers..**.
28880 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
28890 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
288a0 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
288b0 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
288c0 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
288d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
288e0 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
288f0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
28900 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
28910 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
28920 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
28930 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
28940 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
28950 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
28960 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
28970 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
28980 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
28990 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
289a0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
289b0 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
289c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
289d0 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
289e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
289f0 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
28a00 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
28a10 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
28a20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
28a30 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
28a40 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
28a50 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
28a60 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
28a70 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
28a80 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
28a90 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
28aa0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
28ab0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
28ac0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
28ad0 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
28ae0 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
28af0 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
28b00 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
28b10 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
28b20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
28b30 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
28b40 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
28b50 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
28b60 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
28b70 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
28b80 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
28b90 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
28ba0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76  </ul>.**.** Conv
28bb0 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
28bc0 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
28bd0 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
28be0 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
28bf0 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
28c00 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
28c10 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
28c20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
28c30 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
28c40 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
28c50 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f  prior pointer po
28c60 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76  ints to will hav
28c70 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
28c80 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
28c90 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
28ca0 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
28cb0 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
28cc0 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
28cd0 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
28ce0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
28cf0 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
28d00 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
28d10 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
28d20 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
28d30 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20   and easiest to 
28d40 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20  remember policy 
28d50 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
28d60 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
28d70 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
28d80 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
28d90 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
28da0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
28db0 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
28dc0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
28dd0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
28de0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
28df0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
28e00 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
28e10 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
28e20 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
28e30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
28e40 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
28e50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
28e60 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
28e70 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
28e80 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
28e90 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
28ea0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
28eb0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
28ec0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
28ed0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28ee0 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
28ef0 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
28f00 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
28f10 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
28f20 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
28f30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
28f40 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
28f50 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
28f60 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
28f70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
28f80 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
28f90 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
28fa0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
28fb0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
28fc0 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
28fd0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
28fe0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
28ff0 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
29000 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
29010 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
29020 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
29030 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
29040 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
29050 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72  * The pointers r
29060 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
29070 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
29080 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
29090 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
290a0 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
290b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
290c0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
290d0 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
290e0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
290f0 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ] is called.  Th
29100 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
29110 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
29120 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73  ngs.** and BLOBs
29130 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
29140 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e  tically.  Do <b>
29150 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65  not</b> pass the
29160 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
29170 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ed.** [sqlite3_c
29180 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
29190 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
291a0 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
291b0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  o.** [sqlite3_fr
291c0 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ee()]..**.** If 
291d0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
291e0 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
291f0 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c   during the eval
29200 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a  uation of any.**
29210 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
29220 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61  es, a default va
29230 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
29240 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61    The default va
29250 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  lue.** is either
29260 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20   the integer 0, 
29270 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
29280 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f  nt number 0.0, o
29290 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
292a0 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ter.  Subsequent
292b0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
292c0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69  e3_errcode()] wi
292d0 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  ll return.** [SQ
292e0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
292f0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
29300 2a 0a 2a 2a 20 7b 48 31 33 38 30 33 7d 20 54 68  *.** {H13803} Th
29310 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
29320 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74  n_blob(S,N)] int
29330 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
29340 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
29350 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
29360 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
29370 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
29380 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
29390 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
293a0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
293b0 61 20 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e 20  a BLOB and then 
293c0 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20  returns a.**    
293d0 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f        pointer to
293e0 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76   the converted v
293f0 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  alue..**.** {H13
29400 38 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  806} The [sqlite
29410 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53  3_column_bytes(S
29420 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
29430 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20  eturns the.**   
29440 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66         number of
29450 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 42 4c   bytes in the BL
29460 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78  OB or string (ex
29470 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a  clusive of the.*
29480 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20  *          zero 
29490 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68  terminator on th
294a0 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77  e string) that w
294b0 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  as returned by t
294c0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  he.**          m
294d0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
294e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  to [sqlite3_colu
294f0 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72  mn_blob(S,N)] or
29500 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
29510 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
29520 74 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  t(S,N)]..**.** {
29530 48 31 33 38 30 39 7d 20 54 68 65 20 5b 73 71 6c  H13809} The [sql
29540 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
29550 73 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  s16(S,N)] interf
29560 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ace returns the.
29570 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
29580 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
29590 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75  he string (exclu
295a0 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20  sive of the.**  
295b0 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72          zero ter
295c0 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73  minator on the s
295d0 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20  tring) that was 
295e0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
295f0 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74  **          most
29600 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
29610 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
29620 74 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a  text16(S,N)]..**
29630 0a 2a 2a 20 7b 48 31 33 38 31 32 7d 20 54 68 65  .** {H13812} The
29640 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
29650 5f 64 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e  _double(S,N)] in
29660 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
29670 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
29680 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
29690 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
296a0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
296b0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
296c0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
296d0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
296e0 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
296f0 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20  t value and.**  
29700 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
29710 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76  a copy of that v
29720 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  alue..**.** {H13
29730 38 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  815} The [sqlite
29740 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e  3_column_int(S,N
29750 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
29760 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
29770 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
29780 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
29790 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
297a0 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a  t set for the.**
297b0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
297c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
297d0 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73   into a 64-bit s
297e0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
297f0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
29800 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20  turns the lower 
29810 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 74 20  32 bits of that 
29820 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  integer..**.** {
29830 48 31 33 38 31 38 7d 20 54 68 65 20 5b 73 71 6c  H13818} The [sql
29840 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
29850 34 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  4(S,N)] interfac
29860 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
29870 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63  *          Nth c
29880 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
29890 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
298a0 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74  result set for t
298b0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
298c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
298d0 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d  nt] S into a 64-
298e0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
298f0 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  er and.**       
29900 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70     returns a cop
29910 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65  y of that intege
29920 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 31  r..**.** {H13821
29930 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
29940 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d  olumn_text(S,N)]
29950 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
29960 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
29970 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
29980 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
29990 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
299a0 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  set for.**      
299b0 20 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65      the [prepare
299c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
299d0 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  nto a zero-termi
299e0 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20  nated UTF-8.**  
299f0 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61          string a
29a00 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
29a10 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72  nter to that str
29a20 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  ing..**.** {H138
29a30 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  24} The [sqlite3
29a40 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53  _column_text16(S
29a50 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
29a60 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
29a70 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
29a80 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
29a90 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
29aa0 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a  ult set for the.
29ab0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
29ac0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29ad0 20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   S into a zero-t
29ae0 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65  erminated 2-byte
29af0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69  .**          ali
29b00 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69  gned UTF-16 nati
29b10 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 73 74  ve byte order st
29b20 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
29b30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70  .**          a p
29b40 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
29b50 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  tring..**.** {H1
29b60 33 38 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74  3827} The [sqlit
29b70 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53  e3_column_type(S
29b80 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
29b90 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
29ba0 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54     one of [SQLIT
29bb0 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45  E_NULL], [SQLITE
29bc0 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49  _INTEGER], [SQLI
29bd0 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20  TE_FLOAT],.**   
29be0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54         [SQLITE_T
29bf0 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  EXT], or [SQLITE
29c00 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70  _BLOB] as approp
29c10 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20  riate for.**    
29c20 20 20 20 20 20 20 74 68 65 20 4e 74 68 20 63 6f        the Nth co
29c30 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
29c40 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
29c50 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a  esult set for.**
29c60 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70            the [p
29c70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29c80 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  t] S..**.** {H13
29c90 38 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  830} The [sqlite
29ca0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 53  3_column_value(S
29cb0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
29cc0 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20  eturns a.**     
29cd0 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20       pointer to 
29ce0 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
29cf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
29d00 62 6a 65 63 74 20 66 6f 72 20 74 68 65 0a 2a 2a  bject for the.**
29d10 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f            Nth co
29d20 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
29d30 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
29d40 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a  esult set for.**
29d50 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70            the [p
29d60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29d70 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  t] S..*/.const v
29d80 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
29d90 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
29da0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
29db0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
29dc0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
29dd0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
29de0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
29df0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
29e00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29e10 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
29e20 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
29e30 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
29e40 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
29e50 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
29e60 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
29e70 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
29e80 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
29e90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29ea0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
29eb0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
29ec0 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
29ed0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
29ee0 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
29ef0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
29f00 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
29f10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
29f20 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
29f30 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
29f40 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
29f50 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
29f60 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
29f70 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a  .sqlite3_value *
29f80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
29f90 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
29fa0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
29fb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29fc0 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
29fd0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
29fe0 65 63 74 20 7b 48 31 33 33 30 30 7d 20 3c 53 37  ect {H13300} <S7
29ff0 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0300>.**.** The 
2a000 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2a010 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
2a020 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
2a030 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2a040 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68  ement]..** If th
2a050 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
2a060 65 78 65 63 75 74 65 64 20 73 75 63 63 65 73 73  executed success
2a070 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65  fully or not exe
2a080 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68  cuted at all, th
2a090 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20  en.** SQLITE_OK 
2a0a0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20  is returned. If 
2a0b0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
2a0c0 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65   statement faile
2a0d0 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72  d then an.** [er
2a0e0 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78  ror code] or [ex
2a0f0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
2a100 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
2a110 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2a120 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ne can be called
2a130 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75   at any point du
2a140 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ring the executi
2a150 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72  on of the.** [pr
2a160 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a170 5d 2e 20 20 49 66 20 74 68 65 20 76 69 72 74 75  ].  If the virtu
2a180 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e  al machine has n
2a190 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  ot.** completed 
2a1a0 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74  execution when t
2a1b0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63  his routine is c
2a1c0 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c  alled, that is l
2a1d0 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ike.** encounter
2a1e0 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  ing an error or 
2a1f0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  an [sqlite3_inte
2a200 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70  rrupt | interrup
2a210 74 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74  t]..** Incomplet
2a220 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 65  e updates may be
2a230 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64   rolled back and
2a240 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61   transactions ca
2a250 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e  nceled,.** depen
2a260 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63  ding on the circ
2a270 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74  umstances, and t
2a280 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  he.** [error cod
2a290 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c  e] returned will
2a2a0 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52   be [SQLITE_ABOR
2a2b0 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  T]..**.** INVARI
2a2c0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  ANTS:.**.** {H11
2a2d0 33 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  302} The [sqlite
2a2e0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69  3_finalize(S)] i
2a2f0 6e 74 65 72 66 61 63 65 20 64 65 73 74 72 6f 79  nterface destroy
2a300 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2a310 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
2a320 65 6d 65 6e 74 5d 20 53 20 61 6e 64 20 72 65 6c  ement] S and rel
2a330 65 61 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 20 20  eases all.**    
2a340 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64        memory and
2a350 20 66 69 6c 65 20 72 65 73 6f 75 72 63 65 73 20   file resources 
2a360 68 65 6c 64 20 62 79 20 74 68 61 74 20 6f 62 6a  held by that obj
2a370 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33  ect..**.** {H113
2a380 30 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20  04} If the most 
2a390 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2a3a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2a3b0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
2a3c0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
2a3d0 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
2a3e0 72 6e 65 64 20 61 6e 20 65 72 72 6f 72 2c 0a 2a  rned an error,.*
2a3f0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
2a400 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2a410 65 28 53 29 5d 20 72 65 74 75 72 6e 73 20 74 68  e(S)] returns th
2a420 61 74 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a 2a  at same error..*
2a430 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
2a440 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
2a450 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2a460 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2a470 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
2a480 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20  tatement Object 
2a490 7b 48 31 33 33 33 30 7d 20 3c 53 37 30 33 30 30  {H13330} <S70300
2a4a0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
2a4b0 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63  te3_reset() func
2a4c0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
2a4d0 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61  o reset a [prepa
2a4e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2a4f0 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f  * object back to
2a500 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
2a510 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20  te, ready to be 
2a520 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20  re-executed..** 
2a530 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
2a540 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
2a550 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
2a560 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
2a570 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
2a580 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
2a590 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
2a5a0 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
2a5b0 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
2a5c0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
2a5d0 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
2a5e0 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
2a5f0 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 32 7d 20 54  **.** {H11332} T
2a600 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2a610 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
2a620 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
2a630 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a640 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 61  S.**          ba
2a650 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e  ck to the beginn
2a660 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72  ing of its progr
2a670 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33  am..**.** {H1133
2a680 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  4} If the most r
2a690 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2a6a0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2a6b0 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
2a6c0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
2a6d0 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
2a6e0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
2a6f0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
2a700 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ],.**          o
2a710 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
2a720 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
2a730 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
2a740 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20  led on S,.**    
2a750 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69        then [sqli
2a760 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
2a770 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
2a780 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 36  ]..**.** {H11336
2a790 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  } If the most re
2a7a0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2a7b0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2a7c0 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
2a7d0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
2a7e0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
2a7f0 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
2a800 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  en.**          [
2a810 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2a820 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
2a830 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
2a840 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  code]..**.** {H1
2a850 31 33 33 38 7d 20 54 68 65 20 5b 73 71 6c 69 74  1338} The [sqlit
2a860 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
2a870 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
2a880 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
2a890 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  s.**          of
2a8a0 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69   any [sqlite3_bi
2a8b0 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73  nd_blob|bindings
2a8c0 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] on the [prepar
2a8d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
2a8e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2a8f0 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
2a900 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2a910 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
2a920 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
2a930 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48  SQL Functions {H
2a940 31 36 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a  16100} <S20200>.
2a950 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75  ** KEYWORDS: {fu
2a960 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
2a970 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59  routines}.** KEY
2a980 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
2a990 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2a9a0 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59  function}.** KEY
2a9b0 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
2a9c0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2a9d0 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  functions}.**.**
2a9e0 20 54 68 65 73 65 20 74 77 6f 20 66 75 6e 63 74   These two funct
2a9f0 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65  ions (collective
2aa00 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e  ly known as "fun
2aa10 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
2aa20 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65  outines").** are
2aa30 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c   used to add SQL
2aa40 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
2aa50 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72  gregates or to r
2aa60 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61  edefine the beha
2aa70 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74  vior.** of exist
2aa80 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
2aa90 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e  s or aggregates.
2aaa0 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65    The only diffe
2aab0 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20 74 68  rence between th
2aac0 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68 61 74  e.** two is that
2aad0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
2aae0 6d 65 74 65 72 2c 20 74 68 65 20 6e 61 6d 65 20  meter, the name 
2aaf0 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72 29 20  of the (scalar) 
2ab00 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2ab10 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63  ggregate, is enc
2ab20 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f  oded in UTF-8 fo
2ab30 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2ab40 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20  _function() and 
2ab50 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71  UTF-16.** for sq
2ab60 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2ab70 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a  ction16()..**.**
2ab80 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
2ab90 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74  eter is the [dat
2aba0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2abb0 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53  ] to which the S
2abc0 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  QL.** function i
2abd0 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20  s to be added.  
2abe0 49 66 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  If a single prog
2abf0 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ram uses more th
2ac00 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a  an one database.
2ac10 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e  ** connection in
2ac20 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53  ternally, then S
2ac30 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
2ac40 74 20 62 65 20 61 64 64 65 64 20 69 6e 64 69 76  t be added indiv
2ac50 69 64 75 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61  idually to.** ea
2ac60 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
2ac70 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  ection..**.** Th
2ac80 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2ac90 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
2aca0 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
2acb0 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
2acc0 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
2acd0 2e 20 20 54 68 65 20 6c 65 6e 67 74 68 20 6f 66  .  The length of
2ace0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
2acf0 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
2ad00 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 0a  s, exclusive of.
2ad10 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  ** the zero-term
2ad20 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68  inator.  Note th
2ad30 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67  at the name leng
2ad40 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62  th limit is in b
2ad50 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61  ytes, not.** cha
2ad60 72 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74  racters.  Any at
2ad70 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
2ad80 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
2ad90 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
2ada0 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
2adb0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62  [SQLITE_ERROR] b
2adc0 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
2add0 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 70  *.** The third p
2ade0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2adf0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
2ae00 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c  nts that the SQL
2ae10 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2ae20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e  aggregate takes.
2ae30 20 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74   If this paramet
2ae40 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
2ae50 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
2ae60 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
2ae70 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
2ae80 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
2ae90 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  uments..**.** Th
2aea0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2aeb0 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
2aec0 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
2aed0 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
2aee0 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
2aef0 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
2af00 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
2af10 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
2af20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  Any SQL function
2af30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2af40 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74  should be able t
2af50 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77  o work.** work w
2af60 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31  ith UTF-8, UTF-1
2af70 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65  6le, or UTF-16be
2af80 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c  .  But some impl
2af90 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
2afa0 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63  be.** more effic
2afb0 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e  ient with one en
2afc0 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74  coding than anot
2afd0 68 65 72 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f  her.  It is allo
2afe0 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  wed to.** invoke
2aff0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2b000 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71  function() or sq
2b010 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2b020 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70  ction16() multip
2b030 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68  le.** times with
2b040 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2b050 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66  on but with diff
2b060 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20  erent values of 
2b070 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65  eTextRep..** Whe
2b080 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
2b090 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
2b0a0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2b0b0 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
2b0c0 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
2b0d0 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
2b0e0 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
2b0f0 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
2b100 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
2b110 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c   If there is onl
2b120 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65  y a single imple
2b130 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20  mentation which 
2b140 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68  does not care wh
2b150 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64  at text.** encod
2b160 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
2b170 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
2b180 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
2b190 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a  [SQLITE_ANY]..**
2b1a0 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70 61  .** The fifth pa
2b1b0 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
2b1c0 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
2b1d0 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
2b1e0 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
2b1f0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
2b200 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
2b210 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
2b220 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
2b230 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ()]..**.** The s
2b240 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61  eventh, eighth a
2b250 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  nd ninth paramet
2b260 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
2b270 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
2b280 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
2b290 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
2b2a0 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
2b2b0 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
2b2c0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
2b2d0 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20  egate. A scalar 
2b2e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
2b2f0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
2b300 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
2b310 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
2b320 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e   only, NULL poin
2b330 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70  ters should be p
2b340 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74  assed as the xSt
2b350 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a  ep and xFinal.**
2b360 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20   parameters. An 
2b370 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
2b380 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
2b390 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
2b3a0 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e  n of xStep.** an
2b3b0 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
2b3c0 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73  L should be pass
2b3d0 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f  ed for xFunc. To
2b3e0 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
2b3f0 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
2b400 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
2b410 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20  , pass NULL for 
2b420 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
2b430 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a  on callbacks..**
2b440 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74  .** It is permit
2b450 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
2b460 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
2b470 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
2b480 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
2b490 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
2b4a0 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
2b4b0 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
2b4c0 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
2b4d0 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
2b4e0 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
2b4f0 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53  xt encodings.  S
2b500 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
2b510 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
2b520 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  tion most closel
2b530 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
2b540 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
2b550 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
2b560 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  s used..**.** IN
2b570 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2b580 7b 48 31 36 31 30 33 7d 20 54 68 65 20 5b 73 71  {H16103} The [sq
2b590 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2b5a0 63 74 69 6f 6e 31 36 28 29 5d 20 69 6e 74 65 72  ction16()] inter
2b5b0 66 61 63 65 20 62 65 68 61 76 65 73 20 65 78 61  face behaves exa
2b5c0 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ctly.**         
2b5d0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 63   like [sqlite3_c
2b5e0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2b5f0 5d 20 69 6e 20 65 76 65 72 79 20 77 61 79 20 65  ] in every way e
2b600 78 63 65 70 74 20 74 68 61 74 20 69 74 0a 2a 2a  xcept that it.**
2b610 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 70            interp
2b620 72 65 74 73 20 74 68 65 20 7a 46 75 6e 63 74 69  rets the zFuncti
2b630 6f 6e 4e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  onName argument 
2b640 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  as zero-terminat
2b650 65 64 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20  ed UTF-16.**    
2b660 20 20 20 20 20 20 6e 61 74 69 76 65 20 62 79 74        native byt
2b670 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20  e order instead 
2b680 6f 66 20 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69  of as zero-termi
2b690 6e 61 74 65 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a  nated UTF-8..**.
2b6a0 2a 2a 20 7b 48 31 36 31 30 36 7d 20 41 20 73 75  ** {H16106} A su
2b6b0 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
2b6c0 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ion of.**       
2b6d0 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f     the [sqlite3_
2b6e0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2b6f0 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e  D,X,N,E,...)] in
2b700 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
2b710 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  s.**          or
2b720 20 72 65 70 6c 61 63 65 73 20 63 61 6c 6c 62 61   replaces callba
2b730 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20  ck functions in 
2b740 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2b750 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20  nnection] D.**  
2b760 20 20 20 20 20 20 20 20 75 73 65 64 20 74 6f 20          used to 
2b770 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
2b780 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64  L function named
2b790 20 58 20 77 69 74 68 20 4e 20 70 61 72 61 6d 65   X with N parame
2b7a0 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ters.**         
2b7b0 20 61 6e 64 20 68 61 76 69 6e 67 20 61 20 70 72   and having a pr
2b7c0 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
2b7d0 6f 64 69 6e 67 20 6f 66 20 45 2e 0a 2a 2a 0a 2a  oding of E..**.*
2b7e0 2a 20 7b 48 31 36 31 30 39 7d 20 41 20 73 75 63  * {H16109} A suc
2b7f0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
2b800 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2b810 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
2b820 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20  ,P,F,S,L)].**   
2b830 20 20 20 20 20 20 20 72 65 70 6c 61 63 65 73 20         replaces 
2b840 74 68 65 20 50 2c 20 46 2c 20 53 2c 20 61 6e 64  the P, F, S, and
2b850 20 4c 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 61   L values from a
2b860 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 77  ny prior calls w
2b870 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
2b880 74 68 65 20 73 61 6d 65 20 44 2c 20 58 2c 20 4e  the same D, X, N
2b890 2c 20 61 6e 64 20 45 20 76 61 6c 75 65 73 2e 0a  , and E values..
2b8a0 2a 2a 0a 2a 2a 20 7b 48 31 36 31 31 32 7d 20 54  **.** {H16112} T
2b8b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2b8c0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2b8d0 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ...)] interface 
2b8e0 66 61 69 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20  fails with.**   
2b8f0 20 20 20 20 20 20 20 61 20 72 65 74 75 72 6e 20         a return 
2b900 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  code of [SQLITE_
2b910 45 52 52 4f 52 5d 20 69 66 20 74 68 65 20 53 51  ERROR] if the SQ
2b920 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 20  L function name 
2b930 58 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  X is.**         
2b940 20 6c 6f 6e 67 65 72 20 74 68 61 6e 20 32 35 35   longer than 255
2b950 20 62 79 74 65 73 20 65 78 63 6c 75 73 69 76 65   bytes exclusive
2b960 20 6f 66 20 74 68 65 20 7a 65 72 6f 20 74 65 72   of the zero ter
2b970 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b  minator..**.** {
2b980 48 31 36 31 31 38 7d 20 45 69 74 68 65 72 20 46  H16118} Either F
2b990 20 6d 75 73 74 20 62 65 20 4e 55 4c 4c 20 61 6e   must be NULL an
2b9a0 64 20 53 20 61 6e 64 20 4c 20 61 72 65 20 6e 6f  d S and L are no
2b9b0 6e 2d 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 46  n-NULL or else F
2b9c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
2b9d0 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e 64 20 53 20 61  non-NULL and S a
2b9e0 6e 64 20 4c 20 61 72 65 20 4e 55 4c 4c 2c 20 6f  nd L are NULL, o
2b9f0 74 68 65 72 77 69 73 65 0a 2a 2a 20 20 20 20 20  therwise.**     
2ba00 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72       [sqlite3_cr
2ba10 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2ba20 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20  X,N,E,P,F,S,L)] 
2ba30 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
2ba40 45 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ERROR]..**.** {H
2ba50 31 36 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  16121} The [sqli
2ba60 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ba70 69 6f 6e 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65  ion(D,...)] inte
2ba80 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
2ba90 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
2baa0 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53  error code of [S
2bab0 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 66 20 74  QLITE_BUSY] if t
2bac0 68 65 72 65 20 65 78 69 73 74 20 5b 70 72 65 70  here exist [prep
2bad0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2bae0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 73  .**          ass
2baf0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
2bb00 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2bb10 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
2bb20 7b 48 31 36 31 32 34 7d 20 54 68 65 20 5b 73 71  {H16124} The [sq
2bb30 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2bb40 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29  ction(D,X,N,...)
2bb50 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  ] interface fail
2bb60 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20  s with an.**    
2bb70 20 20 20 20 20 20 65 72 72 6f 72 20 63 6f 64 65        error code
2bb80 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f   of [SQLITE_ERRO
2bb90 52 5d 20 69 66 20 70 61 72 61 6d 65 74 65 72 20  R] if parameter 
2bba0 4e 20 28 73 70 65 63 69 66 79 69 6e 67 20 74 68  N (specifying th
2bbb0 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20  e number.**     
2bbc0 20 20 20 20 20 6f 66 20 61 72 67 75 6d 65 6e 74       of argument
2bbd0 73 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  s to the SQL fun
2bbe0 63 74 69 6f 6e 20 62 65 69 6e 67 20 72 65 67 69  ction being regi
2bbf0 73 74 65 72 65 64 29 20 69 73 20 6c 65 73 73 0a  stered) is less.
2bc00 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 6e  **          than
2bc10 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
2bc20 68 61 6e 20 31 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b  han 127..**.** {
2bc30 48 31 36 31 32 37 7d 20 57 68 65 6e 20 4e 20 69  H16127} When N i
2bc40 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
2bc50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
2bc60 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2bc70 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  ,N,...)].**     
2bc80 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 63       interface c
2bc90 61 75 73 65 73 20 63 61 6c 6c 62 61 63 6b 73 20  auses callbacks 
2bca0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f  to be invoked fo
2bcb0 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  r the SQL functi
2bcc0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  on.**          n
2bcd0 61 6d 65 64 20 58 20 77 68 65 6e 20 74 68 65 20  amed X when the 
2bce0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
2bcf0 6e 74 73 20 74 6f 20 74 68 65 20 53 51 4c 20 66  nts to the SQL f
2bd00 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20  unction is.**   
2bd10 20 20 20 20 20 20 20 65 78 61 63 74 6c 79 20 4e         exactly N
2bd20 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 30 7d  ..**.** {H16130}
2bd30 20 57 68 65 6e 20 4e 20 69 73 20 2d 31 2c 20 74   When N is -1, t
2bd40 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2bd50 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2bd60 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  N,...)].**      
2bd70 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 63 61      interface ca
2bd80 75 73 65 73 20 63 61 6c 6c 62 61 63 6b 73 20 74  uses callbacks t
2bd90 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72  o be invoked for
2bda0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2bdb0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61  n.**          na
2bdc0 6d 65 64 20 58 20 77 69 74 68 20 61 6e 79 20 6e  med X with any n
2bdd0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2bde0 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33  ts..**.** {H1613
2bdf0 33 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f  3} When calls to
2be00 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2be10 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2be20 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
2be30 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70    specify multip
2be40 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2be50 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
2be60 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 20 20 20  unction X.**    
2be70 20 20 20 20 20 20 61 6e 64 20 77 68 65 6e 20 6f        and when o
2be80 6e 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ne implementatio
2be90 6e 20 68 61 73 20 4e 3e 3d 30 20 61 6e 64 20 74  n has N>=0 and t
2bea0 68 65 20 6f 74 68 65 72 20 68 61 73 20 4e 3d 28  he other has N=(
2beb0 2d 31 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  -1).**          
2bec0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
2bed0 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  on with a non-ze
2bee0 72 6f 20 4e 20 69 73 20 70 72 65 66 65 72 72 65  ro N is preferre
2bef0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 36  d..**.** {H16136
2bf00 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20  } When calls to 
2bf10 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2bf20 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
2bf30 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
2bf40 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69     specify multi
2bf50 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
2bf60 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
2bf70 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 0a  function X with.
2bf80 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2bf90 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f 66 20 61  same number of a
2bfa0 72 67 75 6d 65 6e 74 73 20 4e 20 62 75 74 20 77  rguments N but w
2bfb0 69 74 68 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a  ith different.**
2bfc0 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64 69            encodi
2bfd0 6e 67 73 20 45 2c 20 74 68 65 6e 20 74 68 65 20  ngs E, then the 
2bfe0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2bff0 68 65 72 65 20 45 20 6d 61 74 63 68 65 73 20 74  here E matches t
2c000 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  he.**          d
2c010 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
2c020 20 69 73 20 70 72 65 66 65 72 72 65 64 2e 0a 2a   is preferred..*
2c030 2a 0a 2a 2a 20 7b 48 31 36 31 33 39 7d 20 46 6f  *.** {H16139} Fo
2c040 72 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 53  r an aggregate S
2c050 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  QL function crea
2c060 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  ted using.**    
2c070 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
2c080 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2c090 2c 58 2c 4e 2c 45 2c 50 2c 30 2c 53 2c 4c 29 5d  ,X,N,E,P,0,S,L)]
2c0a0 20 74 68 65 20 66 69 6e 61 6c 69 7a 65 72 0a 2a   the finalizer.*
2c0b0 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74  *          funct
2c0c0 69 6f 6e 20 4c 20 77 69 6c 6c 20 61 6c 77 61 79  ion L will alway
2c0d0 73 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 78 61  s be invoked exa
2c0e0 63 74 6c 79 20 6f 6e 63 65 20 69 66 20 74 68 65  ctly once if the
2c0f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 65  .**          ste
2c100 70 20 66 75 6e 63 74 69 6f 6e 20 53 20 69 73 20  p function S is 
2c110 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
2c120 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20  re times..**.** 
2c130 7b 48 31 36 31 34 32 7d 20 57 68 65 6e 20 53 51  {H16142} When SQ
2c140 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 65 69 74  Lite invokes eit
2c150 68 65 72 20 74 68 65 20 78 46 75 6e 63 20 6f 72  her the xFunc or
2c160 20 78 53 74 65 70 20 66 75 6e 63 74 69 6f 6e 20   xStep function 
2c170 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  of.**          a
2c180 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
2c190 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2c1a0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 20  on or aggregate 
2c1b0 63 72 65 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  created.**      
2c1c0 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f      by [sqlite3_
2c1d0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2c1e0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63  )] or [sqlite3_c
2c1f0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2c200 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
2c210 20 74 68 65 6e 20 74 68 65 20 61 72 72 61 79 20   then the array 
2c220 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  of [sqlite3_valu
2c230 65 5d 20 6f 62 6a 65 63 74 73 20 70 61 73 73 65  e] objects passe
2c240 64 20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  d as the.**     
2c250 20 20 20 20 20 74 68 69 72 64 20 70 61 72 61 6d       third param
2c260 65 74 65 72 20 61 72 65 20 61 6c 77 61 79 73 20  eter are always 
2c270 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2c280 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2c290 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
2c2a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2c2b0 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
2c2c0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
2c2d0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
2c2e0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
2c2f0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
2c300 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
2c310 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
2c320 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2c330 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2c340 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
2c350 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2c360 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2c370 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2c380 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
2c390 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
2c3a0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2c3b0 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71  function16(.  sq
2c3c0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
2c3d0 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69  st void *zFuncti
2c3e0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
2c3f0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
2c400 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
2c410 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
2c420 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2c430 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2c440 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2c450 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
2c460 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2c470 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2c480 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
2c490 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2c4a0 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
2c4b0 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f  I3REF: Text Enco
2c4c0 64 69 6e 67 73 20 7b 48 31 30 32 36 37 7d 20 3c  dings {H10267} <
2c4d0 53 35 30 32 30 30 3e 20 3c 48 31 36 31 30 30 3e  S50200> <H16100>
2c4e0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
2c4f0 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
2c500 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
2c510 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
2c520 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
2c530 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
2c540 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
2c550 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2c560 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a  TF8           1.
2c570 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2c580 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a  TF16LE        2.
2c590 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2c5a0 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a  TF16BE        3.
2c5b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2c5c0 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
2c5d0 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
2c5e0 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
2c5f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
2c600 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
2c610 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
2c620 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c  ate_function onl
2c630 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
2c640 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
2c650 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74  D  8    /* sqlit
2c660 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2c670 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a  ion only */../*.
2c680 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 73  ** CAPI3REF: Obs
2c690 6f 6c 65 74 65 20 46 75 6e 63 74 69 6f 6e 73 0a  olete Functions.
2c6a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
2c6b0 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 20 6e 6f  tions are all no
2c6c0 77 20 6f 62 73 6f 6c 65 74 65 2e 20 20 49 6e 20  w obsolete.  In 
2c6d0 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
2c6e0 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
2c6f0 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
2c700 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 77 65  h older code, we
2c710 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 73 75 70   continue to sup
2c720 70 6f 72 74 0a 2a 2a 20 74 68 65 73 65 20 66 75  port.** these fu
2c730 6e 63 74 69 6f 6e 73 2e 20 20 48 6f 77 65 76 65  nctions.  Howeve
2c740 72 2c 20 6e 65 77 20 64 65 76 65 6c 6f 70 6d 65  r, new developme
2c750 6e 74 20 70 72 6f 6a 65 63 74 73 20 73 68 6f 75  nt projects shou
2c760 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
2c770 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
2c780 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70  ctions.  To help
2c790 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c   encourage peopl
2c7a0 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73  e to avoid.** us
2c7b0 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69  ing these functi
2c7c0 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20  ons, we are not 
2c7d0 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f  going to tell yo
2c7e0 75 20 77 61 6e 74 20 74 68 65 79 20 64 6f 2e 0a  u want they do..
2c7f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  */.int sqlite3_a
2c800 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
2c810 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2c820 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  ;.int sqlite3_ex
2c830 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
2c840 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  mt*);.int sqlite
2c850 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69  3_transfer_bindi
2c860 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
2c870 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  *, sqlite3_stmt*
2c880 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  );.int sqlite3_g
2c890 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f  lobal_recover(vo
2c8a0 69 64 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  id);.void sqlite
2c8b0 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70  3_thread_cleanup
2c8c0 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
2c8d0 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
2c8e0 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73  (void(*)(void*,s
2c8f0 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74  qlite3_int64,int
2c900 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  ),void*,sqlite3_
2c910 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int64);../*.** C
2c920 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
2c930 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  ng SQL Function 
2c940 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73  Parameter Values
2c950 20 7b 48 31 35 31 30 30 7d 20 3c 53 32 30 32 30   {H15100} <S2020
2c960 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  0>.**.** The C-l
2c970 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
2c980 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
2c990 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
2c9a0 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
2c9b0 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
2c9c0 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
2c9d0 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
2c9e0 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
2c9f0 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
2ca00 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a  or aggregate..**
2ca10 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
2ca20 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
2ca30 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
2ca40 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
2ca50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
2ca60 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2ca70 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
2ca80 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2ca90 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
2caa0 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
2cab0 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
2cac0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2cad0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
2cae0 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61  s..** The 4th pa
2caf0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
2cb00 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
2cb10 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
2cb20 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
2cb30 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2cb40 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
2cb50 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
2cb60 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2cb70 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
2cb80 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
2cb90 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
2cba0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2cbb0 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
2cbc0 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
2cbd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2cbe0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
2cbf0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2cc00 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
2cc10 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2cc20 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2cc30 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
2cc40 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
2cc50 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
2cc60 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2cc70 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
2cc80 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
2cc90 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
2cca0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  r..**.** These r
2ccb0 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
2ccc0 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
2ccd0 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e  sponding [column
2cce0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2ccf0 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  s].** except tha
2cd00 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  t  these routine
2cd10 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
2cd20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2cd30 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2cd40 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
2cd50 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
2cd60 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
2cd70 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
2cd80 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
2cd90 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2cda0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
2cdb0 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
2cdc0 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
2cdd0 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
2cde0 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
2cdf0 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
2ce00 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ne.  The.** sqli
2ce10 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2ce20 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
2ce30 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
2ce40 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
2ce50 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73  extract UTF-16 s
2ce60 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
2ce70 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
2ce80 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
2ce90 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
2cea0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
2ceb0 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
2cec0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
2ced0 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
2cee0 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
2cef0 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
2cf00 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
2cf10 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
2cf20 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
2cf30 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
2cf40 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
2cf50 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
2cf60 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
2cf70 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
2cf80 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
2cf90 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
2cfa0 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
2cfb0 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
2cfc0 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
2cfd0 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
2cfe0 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
2cff0 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
2d000 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
2d010 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
2d020 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
2d030 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
2d040 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
2d050 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
2d060 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  rned..**.** Plea
2d070 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
2d080 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
2d090 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
2d0a0 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65   pointer returne
2d0b0 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
2d0c0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d  e3_value_blob()]
2d0d0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
2d0e0 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _text()], or.** 
2d0f0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2d100 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20  ext16()] can be 
2d110 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61  invalidated by a
2d120 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
2d130 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2d140 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
2d150 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2d160 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69  ytes16()], [sqli
2d170 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
2d180 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
2d190 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
2d1a0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ]..**.** These r
2d1b0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
2d1c0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
2d1d0 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
2d1e0 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
2d1f0 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
2d200 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
2d210 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73  lue*] parameters
2d220 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2d230 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30  TS:.**.** {H1510
2d240 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
2d250 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 69  value_blob(V)] i
2d260 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2d270 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2d280 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2d290 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2d2a0 63 74 20 56 20 69 6e 74 6f 20 61 20 42 4c 4f 42  ct V into a BLOB
2d2b0 20 61 6e 64 20 74 68 65 6e 0a 2a 2a 20 20 20 20   and then.**    
2d2c0 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
2d2d0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63  pointer to the c
2d2e0 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a  onverted value..
2d2f0 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 36 7d 20 54  **.** {H15106} T
2d300 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2d310 65 5f 62 79 74 65 73 28 56 29 5d 20 69 6e 74 65  e_bytes(V)] inte
2d320 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
2d330 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
2d340 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2d350 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
2d360 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f  ing (exclusive o
2d370 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2d380 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f    zero terminato
2d390 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29  r on the string)
2d3a0 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
2d3b0 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
2d3c0 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e        most recen
2d3d0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2d3e0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29  e3_value_blob(V)
2d3f0 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
2d400 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d410 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20  text(V)]..**.** 
2d420 7b 48 31 35 31 30 39 7d 20 54 68 65 20 5b 73 71  {H15109} The [sq
2d430 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2d440 73 31 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63  s16(V)] interfac
2d450 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
2d460 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
2d470 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2d480 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69   string (exclusi
2d490 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  ve of the.**    
2d4a0 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69        zero termi
2d4b0 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72  nator on the str
2d4c0 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65  ing) that was re
2d4d0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
2d4e0 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72            most r
2d4f0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2d500 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2d510 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20 20 20 20  t16(V)],.**     
2d520 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61       [sqlite3_va
2d530 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d  lue_text16be(V)]
2d540 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  , or [sqlite3_va
2d550 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d  lue_text16le(V)]
2d560 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 32 7d  ..**.** {H15112}
2d570 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2d580 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29 5d 20 69  lue_double(V)] i
2d590 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2d5a0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2d5b0 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2d5c0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2d5d0 63 74 20 56 20 69 6e 74 6f 20 61 20 66 6c 6f 61  ct V into a floa
2d5e0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
2d5f0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
2d600 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
2d610 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a  of that value..*
2d620 2a 0a 2a 2a 20 7b 48 31 35 31 31 35 7d 20 54 68  *.** {H15115} Th
2d630 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2d640 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65 72 66 61  _int(V)] interfa
2d650 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2d660 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f  **          [pro
2d670 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2d680 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69  alue] object V i
2d690 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67  nto a 64-bit sig
2d6a0 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a  ned integer and.
2d6b0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
2d6c0 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32  rns the lower 32
2d6d0 20 62 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e   bits of that in
2d6e0 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  teger..**.** {H1
2d6f0 35 31 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74  5118} The [sqlit
2d700 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 56  e3_value_int64(V
2d710 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2d720 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
2d730 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
2d740 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2d750 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
2d760 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
2d770 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20  teger and.**    
2d780 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
2d790 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74  copy of that int
2d7a0 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  eger..**.** {H15
2d7b0 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  121} The [sqlite
2d7c0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d  3_value_text(V)]
2d7d0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2d7e0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2d7f0 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
2d800 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2d810 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65  ject V into a ze
2d820 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
2d830 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  F-8.**          
2d840 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2d850 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2d860 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
2d870 2a 2a 20 7b 48 31 35 31 32 34 7d 20 54 68 65 20  ** {H15124} The 
2d880 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2d890 65 78 74 31 36 28 56 29 5d 20 69 6e 74 65 72 66  ext16(V)] interf
2d8a0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2d8b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2d8c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2d8d0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
2d8e0 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
2d8f0 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a  inated 2-byte.**
2d900 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65            aligne
2d910 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  d UTF-16 native 
2d920 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
2d930 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e         string an
2d940 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
2d950 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
2d960 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32  ng..**.** {H1512
2d970 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
2d980 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56  value_text16be(V
2d990 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2d9a0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
2d9b0 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
2d9c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2d9d0 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
2d9e0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2d9f0 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20  2-byte.**       
2da00 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31     aligned UTF-1
2da10 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20  6 big-endian.** 
2da20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
2da30 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
2da40 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
2da50 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ring..**.** {H15
2da60 31 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  130} The [sqlite
2da70 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
2da80 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
2da90 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2daa0 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
2dab0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2dac0 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
2dad0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2dae0 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20  d 2-byte.**     
2daf0 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46       aligned UTF
2db00 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  -16 little-endia
2db10 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  n.**          st
2db20 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2db30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2db40 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  at string..**.**
2db50 20 7b 48 31 35 31 33 33 7d 20 54 68 65 20 5b 73   {H15133} The [s
2db60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
2db70 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(V)] interface 
2db80 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
2db90 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49      one of [SQLI
2dba0 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54  TE_NULL], [SQLIT
2dbb0 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c  E_INTEGER], [SQL
2dbc0 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20  ITE_FLOAT],.**  
2dbd0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
2dbe0 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  TEXT], or [SQLIT
2dbf0 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f  E_BLOB] as appro
2dc00 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20  priate for.**   
2dc10 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69         the [sqli
2dc20 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2dc30 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31  t V..**.** {H151
2dc40 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  36} The [sqlite3
2dc50 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
2dc60 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  ype(V)] interfac
2dc70 65 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 20 20  e converts.**   
2dc80 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 6f 74         the [prot
2dc90 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2dca0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
2dcb0 74 6f 20 65 69 74 68 65 72 20 61 6e 20 69 6e 74  to either an int
2dcc0 65 67 65 72 20 6f 72 0a 2a 2a 20 20 20 20 20 20  eger or.**      
2dcd0 20 20 20 20 61 20 66 6c 6f 61 74 69 6e 67 20 70      a floating p
2dce0 6f 69 6e 74 20 76 61 6c 75 65 20 69 66 20 69 74  oint value if it
2dcf0 20 63 61 6e 20 64 6f 20 73 6f 20 77 69 74 68 6f   can do so witho
2dd00 75 74 20 6c 6f 73 73 20 6f 66 0a 2a 2a 20 20 20  ut loss of.**   
2dd10 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61 74 69         informati
2dd20 6f 6e 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  on, and returns 
2dd30 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e  one of [SQLITE_N
2dd40 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ULL],.**        
2dd50 20 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45    [SQLITE_INTEGE
2dd60 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  R], [SQLITE_FLOA
2dd70 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
2dd80 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
2dd90 20 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20    [SQLITE_BLOB] 
2dda0 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  as appropriate f
2ddb0 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
2ddc0 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
2ddd0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2dde0 65 63 74 20 56 20 61 66 74 65 72 20 74 68 65 20  ect V after the 
2ddf0 63 6f 6e 76 65 72 73 69 6f 6e 20 61 74 74 65 6d  conversion attem
2de00 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  pt..*/.const voi
2de10 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
2de20 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
2de30 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2de40 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
2de50 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2de60 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2de70 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
2de80 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c  3_value*);.doubl
2de90 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
2dea0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
2deb0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2dec0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
2ded0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73  lite3_value*);.s
2dee0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
2def0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
2df00 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2df10 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
2df20 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
2df30 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
2df40 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
2df50 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
2df60 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
2df70 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
2df80 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2df90 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
2dfa0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2dfb0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2dfc0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2dfd0 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
2dfe0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2dff0 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
2e000 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2e010 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
2e020 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
2e030 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
2e040 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
2e050 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
2e060 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
2e070 7b 48 31 36 32 31 30 7d 20 3c 53 32 30 32 30 30  {H16210} <S20200
2e080 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c  >.**.** The impl
2e090 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67  ementation of ag
2e0a0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
2e0b0 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72  tions use this r
2e0c0 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
2e0d0 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72  te.** a structur
2e0e0 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  e for storing th
2e0f0 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
2e100 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   The first time 
2e110 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
2e120 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
2e130 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
2e140 64 20 66 6f 72 20 61 0a 2a 2a 20 70 61 72 74 69  d for a.** parti
2e150 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c  cular aggregate,
2e160 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65   SQLite allocate
2e170 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f  s nBytes of memo
2e180 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
2e190 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61  hat.** memory, a
2e1a0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
2e1b0 6e 74 65 72 20 74 6f 20 69 74 2e 20 4f 6e 20 73  nter to it. On s
2e1c0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
2e1d0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
2e1e0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2e1f0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
2e200 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
2e210 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64  ate function ind
2e220 65 78 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ex,.** the same 
2e230 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
2e240 65 64 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  ed. The implemen
2e250 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 61 67  tation of the ag
2e260 67 72 65 67 61 74 65 20 63 61 6e 20 75 73 65 0a  gregate can use.
2e270 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 65 64 20  ** the returned 
2e280 62 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75  buffer to accumu
2e290 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  late data..**.**
2e2a0 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69   SQLite automati
2e2b0 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
2e2c0 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72  allocated buffer
2e2d0 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
2e2e0 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e  ate.** query con
2e2f0 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
2e300 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2e310 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f  r should be a co
2e320 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  py of the.** [sq
2e330 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
2e340 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
2e350 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
2e360 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2e370 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
2e380 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
2e390 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
2e3a0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
2e3b0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
2e3c0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
2e3d0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
2e3e0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
2e3f0 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
2e400 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2e410 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
2e420 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
2e430 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 31 7d 20  .**.** {H16211} 
2e440 54 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61  The first invoca
2e450 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
2e460 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2e470 78 74 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20  xt(C,N)] for.** 
2e480 20 20 20 20 20 20 20 20 20 61 20 70 61 72 74 69           a parti
2e490 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f  cular instance o
2e4a0 66 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 66  f an aggregate f
2e4b0 75 6e 63 74 69 6f 6e 20 28 66 6f 72 20 61 20 70  unction (for a p
2e4c0 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20  articular.**    
2e4d0 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 29        context C)
2e4e0 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
2e4f0 6f 20 61 6c 6c 6f 63 61 74 65 20 4e 20 62 79 74  o allocate N byt
2e500 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  es of memory,.**
2e510 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
2e520 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
2e530 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72  return a pointer
2e540 20 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   to the allocate
2e550 64 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  d memory..**.** 
2e560 7b 48 31 36 32 31 33 7d 20 49 66 20 61 20 6d 65  {H16213} If a me
2e570 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2e580 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
2e590 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
2e5a0 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
2e5b0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d  te_context(C,N)]
2e5c0 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   then the functi
2e5d0 6f 6e 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  on returns 0..**
2e5e0 0a 2a 2a 20 7b 48 31 36 32 31 35 7d 20 53 65 63  .** {H16215} Sec
2e5f0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
2e600 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  nt invocations o
2e610 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  f.**          [s
2e620 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2e630 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66  _context(C,N)] f
2e640 6f 72 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74  or the same cont
2e650 65 78 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a  ext pointer C.**
2e660 20 20 20 20 20 20 20 20 20 20 69 67 6e 6f 72 65            ignore
2e670 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
2e680 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f   and return a po
2e690 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 61 6d  inter to the sam
2e6a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6c  e.**          bl
2e6b0 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65  ock of memory re
2e6c0 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 66 69  turned by the fi
2e6d0 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a  rst invocation..
2e6e0 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 37 7d 20 54  **.** {H16217} T
2e6f0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
2e700 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ted by [sqlite3_
2e710 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2e720 74 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20  t(C,N)] is.**   
2e730 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63         automatic
2e740 61 6c 6c 79 20 66 72 65 65 64 20 6f 6e 20 74 68  ally freed on th
2e750 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b  e next call to [
2e760 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2e770 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
2e780 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2e790 65 28 29 5d 20 66 6f 72 20 74 68 65 20 5b 70 72  e()] for the [pr
2e7a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e7b0 5d 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20  ] containing.** 
2e7c0 20 20 20 20 20 20 20 20 20 74 68 65 20 61 67 67           the agg
2e7d0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
2e7e0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2e7f0 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f  context C..*/.vo
2e800 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
2e810 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
2e820 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2e830 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
2e840 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
2e850 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
2e860 74 69 6f 6e 73 20 7b 48 31 36 32 34 30 7d 20 3c  tions {H16240} <
2e870 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
2e880 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
2e890 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
2e8a0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2e8b0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
2e8c0 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
2e8d0 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
2e8e0 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
2e8f0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
2e900 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2e910 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
2e920 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2e930 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2e940 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
2e950 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
2e960 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
2e970 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
2e980 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a  function. {END}.
2e990 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2e9a0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
2e9b0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2e9c0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
2e9d0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
2e9e0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2e9f0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2ea00 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2ea10 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 34 33 7d  :.**.** {H16243}
2ea20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 73   The [sqlite3_us
2ea30 65 72 5f 64 61 74 61 28 43 29 5d 20 69 6e 74 65  er_data(C)] inte
2ea40 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2ea50 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20  copy of the.**  
2ea60 20 20 20 20 20 20 20 20 50 20 70 6f 69 6e 74 65          P pointe
2ea70 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  r from the [sqli
2ea80 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ea90 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  ion(D,X,N,E,P,F,
2eaa0 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,L)].**        
2eab0 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72    or [sqlite3_cr
2eac0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2ead0 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
2eae0 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20  ] call that.**  
2eaf0 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
2eb00 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ed the SQL funct
2eb10 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77  ion associated w
2eb20 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ith [sqlite3_con
2eb30 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64  text] C..*/.void
2eb40 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   *sqlite3_user_d
2eb50 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
2eb60 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
2eb70 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2eb80 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20   Connection For 
2eb90 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 35  Functions {H1625
2eba0 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
2ebb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
2ebc0 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61  handle() interfa
2ebd0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
2ebe0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
2ebf0 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ter to the [data
2ec00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2ec10 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65   (the 1st parame
2ec20 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
2ec30 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2ec40 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
2ec50 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2ec60 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
2ec70 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
2ec80 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
2ec90 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
2eca0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
2ecb0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  unction..**.** I
2ecc0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2ecd0 20 7b 48 31 36 32 35 33 7d 20 54 68 65 20 5b 73   {H16253} The [s
2ece0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
2ecf0 62 5f 68 61 6e 64 6c 65 28 43 29 5d 20 69 6e 74  b_handle(C)] int
2ed00 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2ed10 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
2ed20 20 20 20 20 20 20 20 20 20 44 20 70 6f 69 6e 74           D point
2ed30 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  er from the [sql
2ed40 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2ed50 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  tion(D,X,N,E,P,F
2ed60 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,S,L)].**       
2ed70 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63     or [sqlite3_c
2ed80 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2ed90 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
2eda0 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20  )] call that.** 
2edb0 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65           registe
2edc0 72 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  red the SQL func
2edd0 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20  tion associated 
2ede0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f  with [sqlite3_co
2edf0 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71 6c  ntext] C..*/.sql
2ee00 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f  ite3 *sqlite3_co
2ee10 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
2ee20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2ee30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ee40 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
2ee50 69 6c 69 61 72 79 20 44 61 74 61 20 7b 48 31 36  iliary Data {H16
2ee60 32 37 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  270} <S20200>.**
2ee70 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** The followin
2ee80 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20  g two functions 
2ee90 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73  may be used by s
2eea0 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
2eeb0 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69  ons to.** associ
2eec0 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74  ate metadata wit
2eed0 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  h argument value
2eee0 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76  s. If the same v
2eef0 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74  alue is passed t
2ef00 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e  o.** multiple in
2ef10 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
2ef20 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
2ef30 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20  on during query 
2ef40 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72  execution, under
2ef50 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73  .** some circums
2ef60 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63  tances the assoc
2ef70 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d  iated metadata m
2ef80 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
2ef90 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20   This may.** be 
2efa0 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c  used, for exampl
2efb0 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75  e, to add a regu
2efc0 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d  lar-expression m
2efd0 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a  atching scalar.*
2efe0 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  * function. The 
2eff0 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e  compiled version
2f000 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20   of the regular 
2f010 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74  expression is st
2f020 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64  ored as.** metad
2f030 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
2f040 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75  ith the SQL valu
2f050 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
2f060 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
2f070 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20  on.** pattern.  
2f080 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67  The compiled reg
2f090 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
2f0a0 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e  can be reused on
2f0b0 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76   multiple.** inv
2f0c0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
2f0d0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f  same function so
2f0e0 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e   that the origin
2f0f0 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  al pattern strin
2f100 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65  g.** does not ne
2f110 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69  ed to be recompi
2f120 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f  led on each invo
2f130 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  cation..**.** Th
2f140 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
2f150 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
2f160 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2f170 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64  ter to the metad
2f180 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
2f190 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
2f1a0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66  _set_auxdata() f
2f1b0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
2f1c0 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   Nth argument.**
2f1d0 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70   value to the ap
2f1e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2f1f0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20 6e  d function. If n
2f200 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62  o metadata has b
2f210 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e  een ever.** been
2f220 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68   set for the Nth
2f230 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
2f240 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66   function, or if
2f250 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
2f260 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  ng.** function p
2f270 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61  arameter has cha
2f280 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d  nged since the m
2f290 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74  eta-data was set
2f2a0 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65  ,.** then sqlite
2f2b0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
2f2c0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
2f2d0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
2f2e0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
2f2f0 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
2f300 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61  e saves the meta
2f310 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  data.** pointed 
2f320 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61  to by its 3rd pa
2f330 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d  rameter as the m
2f340 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20  etadata for the 
2f350 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  N-th.** argument
2f360 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2f370 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2f380 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e  tion.  Subsequen
2f390 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  t.** calls to sq
2f3a0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2f3b0 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e  a() might return
2f3c0 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69   this data, if i
2f3d0 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65  t has.** not bee
2f3e0 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20  n destroyed..** 
2f3f0 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c  If it is not NUL
2f400 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  L, SQLite will i
2f410 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
2f420 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ctor.** function
2f430 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74   given by the 4t
2f440 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2f450 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2f460 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d  ta() on.** the m
2f470 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65  etadata when the
2f480 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66   corresponding f
2f490 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
2f4a0 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20  r changes.** or 
2f4b0 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  when the SQL sta
2f4c0 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73  tement completes
2f4d0 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
2f4e0 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53  s first..**.** S
2f4f0 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f  QLite is free to
2f500 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75   call the destru
2f510 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65  ctor and drop me
2f520 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a  tadata on any.**
2f530 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e   parameter of an
2f540 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e  y function at an
2f550 79 20 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c  y time.  The onl
2f560 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74  y guarantee is t
2f570 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72  hat.** the destr
2f580 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61  uctor will be ca
2f590 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20  lled before the 
2f5a0 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f 70  metadata is drop
2f5b0 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72  ped..**.** In pr
2f5c0 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61  actice, metadata
2f5d0 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65   is preserved be
2f5e0 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63  tween function c
2f5f0 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72  alls for.** expr
2f600 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65  essions that are
2f610 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d   constant at com
2f620 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20  pile time. This 
2f630 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c  includes literal
2f640 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53  .** values and S
2f650 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a  QL variables..**
2f660 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2f670 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
2f680 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2f690 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
2f6a0 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
2f6b0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2f6c0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2f6d0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 32 7d  :.**.** {H16272}
2f6e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65   The [sqlite3_ge
2f6f0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 5d 20  t_auxdata(C,N)] 
2f700 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2f710 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20  s a pointer.**  
2f720 20 20 20 20 20 20 20 20 74 6f 20 6d 65 74 61 64          to metad
2f730 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
2f740 69 74 68 20 74 68 65 20 4e 74 68 20 70 61 72 61  ith the Nth para
2f750 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c  meter of the SQL
2f760 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
2f770 20 20 20 20 20 20 77 68 6f 73 65 20 63 6f 6e 74        whose cont
2f780 65 78 74 20 69 73 20 43 2c 20 6f 72 20 4e 55 4c  ext is C, or NUL
2f790 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f  L if there is no
2f7a0 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
2f7b0 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ated.**         
2f7c0 20 77 69 74 68 20 74 68 61 74 20 70 61 72 61 6d   with that param
2f7d0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  eter..**.** {H16
2f7e0 32 37 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  274} The [sqlite
2f7f0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
2f800 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  N,P,D)] interfac
2f810 65 20 61 73 73 69 67 6e 73 20 61 20 6d 65 74 61  e assigns a meta
2f820 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  data.**         
2f830 20 70 6f 69 6e 74 65 72 20 50 20 74 6f 20 74 68   pointer P to th
2f840 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20  e Nth parameter 
2f850 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
2f860 69 6f 6e 20 77 69 74 68 20 63 6f 6e 74 65 78 74  ion with context
2f870 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37   C..**.** {H1627
2f880 36 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69  6} SQLite will i
2f890 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
2f8a0 63 74 6f 72 20 44 20 77 69 74 68 20 61 20 73 69  ctor D with a si
2f8b0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  ngle argument.**
2f8c0 20 20 20 20 20 20 20 20 20 20 77 68 69 63 68 20            which 
2f8d0 69 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  is the metadata 
2f8e0 70 6f 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f 77  pointer P follow
2f8f0 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ing a call to.**
2f900 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2f910 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
2f920 2c 4e 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53 51  ,N,P,D)] when SQ
2f930 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68  Lite ceases to h
2f940 6f 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  old.**          
2f950 74 68 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a 2a  the metadata..**
2f960 0a 2a 2a 20 7b 48 31 36 32 37 37 7d 20 53 51 4c  .** {H16277} SQL
2f970 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f  ite ceases to ho
2f980 6c 64 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  ld metadata for 
2f990 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
2f9a0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
2f9b0 20 20 20 20 20 20 77 68 65 6e 20 74 68 65 20 76        when the v
2f9c0 61 6c 75 65 20 6f 66 20 74 68 61 74 20 70 61 72  alue of that par
2f9d0 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2e 0a  ameter changes..
2f9e0 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 38 7d 20 57  **.** {H16278} W
2f9f0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  hen [sqlite3_set
2fa00 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44  _auxdata(C,N,P,D
2fa10 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  )] is invoked, t
2fa20 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
2fa30 20 20 20 20 20 20 20 20 20 20 69 73 20 63 61 6c            is cal
2fa40 6c 65 64 20 66 6f 72 20 61 6e 79 20 70 72 69 6f  led for any prio
2fa50 72 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  r metadata assoc
2fa60 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 73  iated with the s
2fa70 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ame function.** 
2fa80 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74           context
2fa90 20 43 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72   C and parameter
2faa0 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37   N..**.** {H1627
2fab0 39 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63  9} SQLite will c
2fac0 61 6c 6c 20 64 65 73 74 72 75 63 74 6f 72 73 20  all destructors 
2fad0 66 6f 72 20 61 6e 79 20 6d 65 74 61 64 61 74 61  for any metadata
2fae0 20 69 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a 2a   it is holding.*
2faf0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 61 20  *          in a 
2fb00 70 61 72 74 69 63 75 6c 61 72 20 5b 70 72 65 70  particular [prep
2fb10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2fb20 53 20 77 68 65 6e 20 65 69 74 68 65 72 0a 2a 2a  S when either.**
2fb30 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2fb40 65 33 5f 72 65 73 65 74 28 53 29 5d 20 6f 72 20  e3_reset(S)] or 
2fb50 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2fb60 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  e(S)] is called.
2fb70 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2fb80 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_get_auxdata(sq
2fb90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2fba0 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c  int N);.void sql
2fbb0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2fbc0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2fbd0 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c  *, int N, void*,
2fbe0 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29   void (*)(void*)
2fbf0 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
2fc00 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44  REF: Constants D
2fc10 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20  efining Special 
2fc20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76  Destructor Behav
2fc30 69 6f 72 20 7b 48 31 30 32 38 30 7d 0a 2a 2a 0a  ior {H10280}.**.
2fc40 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
2fc50 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
2fc60 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
2fc70 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
2fc80 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
2fc90 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
2fca0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
2fcb0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
2fcc0 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73 74  )].  If the dest
2fcd0 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
2fce0 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
2fcf0 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
2fd00 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
2fd10 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
2fd20 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
2fd30 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
2fd40 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
2fd50 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
2fd60 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   The.** SQLITE_T
2fd70 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d  RANSIENT value m
2fd80 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
2fd90 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c  ntent will likel
2fda0 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74  y change in.** t
2fdb0 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61  he near future a
2fdc0 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73  nd that SQLite s
2fdd0 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f  hould make its o
2fde0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
2fdf0 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
2fe00 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  t before returni
2fe10 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79  ng..**.** The ty
2fe20 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61  pedef is necessa
2fe30 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  ry to work aroun
2fe40 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65  d problems in ce
2fe50 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d  rtain.** C++ com
2fe60 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63  pilers.  See tic
2fe70 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79  ket #2191..*/.ty
2fe80 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
2fe90 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
2fea0 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64  type)(void*);.#d
2feb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
2fec0 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74  TIC      ((sqlit
2fed0 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
2fee0 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51  pe)0).#define SQ
2fef0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20  LITE_TRANSIENT  
2ff00 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
2ff10 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a  uctor_type)-1)..
2ff20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ff30 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75  Setting The Resu
2ff40 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e  lt Of An SQL Fun
2ff50 63 74 69 6f 6e 20 7b 48 31 36 34 30 30 7d 20 3c  ction {H16400} <
2ff60 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
2ff70 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2ff80 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
2ff90 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
2ffa0 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
2ffb0 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
2ffc0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
2ffd0 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
2ffe0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2fff0 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
30000 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
30010 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
30020 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
30030 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
30040 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
30050 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
30060 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d   like the [param
30070 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61  eter binding] fa
30080 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74  mily of.** funct
30090 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e  ions used to bin
300a0 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
300b0 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
300c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
300d0 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
300e0 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  the [SQL paramet
300f0 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  er] documentatio
30100 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
30110 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
30120 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
30130 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e  result_blob() in
30140 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
30150 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
30160 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
30170 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
30180 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77  to be the BLOB w
30190 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20  hose content is 
301a0 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79  pointed.** to by
301b0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
301c0 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20  meter and which 
301d0 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20  is N bytes long 
301e0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
301f0 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
30200 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
30210 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
30220 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
30230 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74  s set the result
30240 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
30250 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
30260 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
30270 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20  BLOB containing 
30280 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65  all zero.** byte
30290 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e  s and N bytes in
302a0 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69   size, where N i
302b0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
302c0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
302d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
302e0 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
302f0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
30300 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
30310 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
30320 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
30330 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
30340 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
30350 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
30360 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
30370 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ent..**.** The s
30380 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
30390 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
303a0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
303b0 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
303c0 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
303d0 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
303e0 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
303f0 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c  xception..** SQL
30400 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
30410 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
30420 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
30430 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
30440 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
30450 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
30460 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
30470 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
30480 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
30490 20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72    SQLite interpr
304a0 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
304b0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
304c0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
304d0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
304e0 54 46 2d 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20  TF-8. SQLite.** 
304f0 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73  interprets the s
30500 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
30510 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
30520 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e  6() as UTF-16 in
30530 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20   native.** byte 
30540 6f 72 64 65 72 2e 20 20 49 66 20 74 68 65 20 74  order.  If the t
30550 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
30560 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
30570 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
30580 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
30590 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74  ror16() is negat
305a0 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
305b0 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72  takes as the err
305c0 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c  or.** message al
305d0 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67  l text up throug
305e0 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
305f0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
30600 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
30610 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
30620 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
30630 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  or.** sqlite3_re
30640 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
30650 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74  s non-negative t
30660 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
30670 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79   that many.** by
30680 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
30690 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e  ers) from the 2n
306a0 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
306b0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
306c0 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
306d0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
306e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
306f0 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
30700 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20  routines make a 
30710 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
30720 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
30730 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a  e text before.**
30740 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48   they return.  H
30750 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e  ence, the callin
30760 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64  g function can d
30770 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20  eallocate or.** 
30780 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20  modify the text 
30790 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72  after they retur
307a0 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  n without harm..
307b0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
307c0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
307d0 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e  () function chan
307e0 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ges the error co
307f0 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  de.** returned b
30800 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65  y SQLite as a re
30810 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  sult of an error
30820 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20   in a function. 
30830 20 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20   By default,.** 
30840 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69  the error code i
30850 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20  s SQLITE_ERROR. 
30860 20 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   A subsequent ca
30870 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  ll to sqlite3_re
30880 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
30890 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
308a0 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65  t_error16() rese
308b0 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ts the error cod
308c0 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f  e to SQLITE_ERRO
308d0 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  R..**.** The sql
308e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62  ite3_result_toob
308f0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  ig() interface c
30900 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
30910 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a  throw an error.*
30920 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  * indicating tha
30930 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  t a string or BL
30940 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 20 74 6f  OB is to long to
30950 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a   represent..**.*
30960 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
30970 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74  sult_nomem() int
30980 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
30990 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
309a0 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
309b0 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f  ting that a memo
309c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
309d0 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  iled..**.** The 
309e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
309f0 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
30a00 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
30a10 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
30a20 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
30a30 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
30a40 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
30a50 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
30a60 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
30a70 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
30a80 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
30a90 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
30aa0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
30ab0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
30ac0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
30ad0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
30ae0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
30af0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
30b00 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
30b10 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
30b20 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
30b30 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
30b40 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
30b50 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
30b60 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
30b70 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
30b80 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
30b90 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
30ba0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
30bb0 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c  sult_text(), sql
30bc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
30bd0 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  16(),.** sqlite3
30be0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
30bf0 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
30c00 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
30c10 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
30c20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76  set the return v
30c30 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c  alue of the appl
30c40 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
30c50 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  function to be.*
30c60 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  * a text string 
30c70 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65  which is represe
30c80 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55  nted as UTF-8, U
30c90 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
30ca0 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d  e order,.** UTF-
30cb0 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e  16 little endian
30cc0 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20  , or UTF-16 big 
30cd0 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
30ce0 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  vely..** SQLite 
30cf0 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72  takes the text r
30d00 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61  esult from the a
30d10 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a  pplication from.
30d20 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  ** the 2nd param
30d30 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69  eter of the sqli
30d40 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
30d50 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
30d60 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
30d70 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
30d80 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
30d90 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
30da0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
30db0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65   SQLite takes re
30dc0 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74  sult text from t
30dd0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
30de0 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20  .** through the 
30df0 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
30e00 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  cter..** If the 
30e10 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
30e20 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
30e30 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
30e40 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e  aces.** is non-n
30e50 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73  egative, then as
30e60 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74   many bytes (not
30e70 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20   characters) of 
30e80 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e  the text.** poin
30e90 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e  ted to by the 2n
30ea0 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20  d parameter are 
30eb0 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70  taken as the app
30ec0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
30ed0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73  .** function res
30ee0 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34  ult..** If the 4
30ef0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
30f00 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
30f10 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
30f20 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
30f30 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
30f40 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
30f50 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
30f60 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66   calls that.** f
30f70 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64  unction as the d
30f80 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
30f90 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
30fa0 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73  sult when it has
30fb0 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69  .** finished usi
30fc0 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
30fd0 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61  ** If the 4th pa
30fe0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
30ff0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31000 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f  xt* interfaces o
31010 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
31020 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
31030 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
31040 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
31050 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  then SQLite.** a
31060 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20  ssumes that the 
31070 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
31080 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61  ult is in consta
31090 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  nt space and doe
310a0 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68  s not.** copy th
310b0 65 20 69 74 20 6f 72 20 63 61 6c 6c 20 61 20 64  e it or call a d
310c0 65 73 74 72 75 63 74 6f 72 20 77 68 65 6e 20 69  estructor when i
310d0 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
310e0 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
310f0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20  ..** If the 4th 
31100 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
31110 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31120 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
31130 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
31140 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
31150 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
31160 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  nt SQLITE_TRANSI
31170 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69  ENT.** then SQLi
31180 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
31190 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  of the result in
311a0 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65  to space obtaine
311b0 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b  d from.** from [
311c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
311d0 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75  ] before it retu
311e0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rns..**.** The s
311f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
31200 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
31210 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
31220 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
31230 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
31240 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63  nction to be a c
31250 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72  opy the.** [unpr
31260 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
31270 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70  value] object sp
31280 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
31290 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
312a0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  he.** sqlite3_re
312b0 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
312c0 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63  erface makes a c
312d0 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
312e0 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f  te3_value].** so
312f0 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
31300 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66  e3_value] specif
31310 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d  ied in the param
31320 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20  eter may change 
31330 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63  or.** be dealloc
31340 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ated after sqlit
31350 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
31360 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75  ) returns withou
31370 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72  t harm..** A [pr
31380 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
31390 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61  value] object ma
313a0 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64  y always be used
313b0 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e   where an.** [un
313c0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
313d0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
313e0 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20  is required, so 
313f0 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f  either.** kind o
31400 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
31410 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20  ] object can be 
31420 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69  used with this i
31430 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
31440 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  If these routine
31450 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  s are called fro
31460 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66  m within the dif
31470 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a  ferent thread.**
31480 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f   than the one co
31490 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70  ntaining the app
314a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
314b0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72   function that r
314c0 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b  eceived.** the [
314d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
314e0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65   pointer, the re
314f0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
31500 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ned..**.** INVAR
31510 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
31520 36 34 30 33 7d 20 54 68 65 20 64 65 66 61 75 6c  6403} The defaul
31530 74 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  t return value f
31540 72 6f 6d 20 61 6e 79 20 53 51 4c 20 66 75 6e 63  rom any SQL func
31550 74 69 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  tion is NULL..**
31560 0a 2a 2a 20 7b 48 31 36 34 30 36 7d 20 54 68 65  .** {H16406} The
31570 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
31580 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 20  _blob(C,V,N,D)] 
31590 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
315a0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
315b0 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
315c0 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
315d0 62 65 20 61 20 42 4c 4f 42 20 74 68 61 74 20 69  be a BLOB that i
315e0 73 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20  s N bytes.**    
315f0 20 20 20 20 20 20 69 6e 20 6c 65 6e 67 74 68 20        in length 
31600 61 6e 64 20 77 69 74 68 20 63 6f 6e 74 65 6e 74  and with content
31610 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56   pointed to by V
31620 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 39 7d  ..**.** {H16409}
31630 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
31640 73 75 6c 74 5f 64 6f 75 62 6c 65 28 43 2c 56 29  sult_double(C,V)
31650 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
31660 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
31670 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
31680 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
31690 6f 20 62 65 20 74 68 65 20 66 6c 6f 61 74 69 6e  o be the floatin
316a0 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 56 2e  g point value V.
316b0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 32 7d 20  .**.** {H16412} 
316c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
316d0 75 6c 74 5f 65 72 72 6f 72 28 43 2c 56 2c 4e 29  ult_error(C,V,N)
316e0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
316f0 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
31700 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
31710 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
31720 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f  o be an exceptio
31730 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64  n with error cod
31740 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  e.**          [S
31750 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64  QLITE_ERROR] and
31760 20 61 20 55 54 46 2d 38 20 65 72 72 6f 72 20 6d   a UTF-8 error m
31770 65 73 73 61 67 65 20 63 6f 70 69 65 64 20 66 72  essage copied fr
31780 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65 0a 2a  om V up to the.*
31790 2a 20 20 20 20 20 20 20 20 20 20 66 69 72 73 74  *          first
317a0 20 7a 65 72 6f 20 62 79 74 65 20 6f 72 20 75 6e   zero byte or un
317b0 74 69 6c 20 4e 20 62 79 74 65 73 20 61 72 65 20  til N bytes are 
317c0 72 65 61 64 20 69 66 20 4e 20 69 73 20 70 6f 73  read if N is pos
317d0 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  itive..**.** {H1
317e0 36 34 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74  6415} The [sqlit
317f0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
31800 36 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66  6(C,V,N)] interf
31810 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20  ace changes the 
31820 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
31830 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63     value of func
31840 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20  tion C to be an 
31850 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65  exception with e
31860 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20  rror code.**    
31870 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52        [SQLITE_ER
31880 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 2d 31  ROR] and a UTF-1
31890 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
318a0 64 65 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67  der error messag
318b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
318c0 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74  pied from V up t
318d0 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
318e0 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 72 20 75   terminator or u
318f0 6e 74 69 6c 20 4e 20 62 79 74 65 73 0a 2a 2a 20  ntil N bytes.** 
31900 20 20 20 20 20 20 20 20 20 61 72 65 20 72 65 61           are rea
31910 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69  d if N is positi
31920 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31  ve..**.** {H1641
31930 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  8} The [sqlite3_
31940 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
31950 62 69 67 28 43 29 5d 20 69 6e 74 65 72 66 61 63  big(C)] interfac
31960 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65  e changes the re
31970 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
31980 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75   value of the fu
31990 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
319a0 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68  n exception with
319b0 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20   error code.**  
319c0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
319d0 54 4f 4f 42 49 47 5d 20 61 6e 64 20 61 6e 20 61  TOOBIG] and an a
319e0 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
319f0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
31a00 7b 48 31 36 34 32 31 7d 20 54 68 65 20 5b 73 71  {H16421} The [sq
31a10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
31a20 6f 72 5f 6e 6f 6d 65 6d 28 43 29 5d 20 69 6e 74  or_nomem(C)] int
31a30 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
31a40 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20  he return.**    
31a50 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74        value of t
31a60 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  he function C to
31a70 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e   be an exception
31a80 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65   with error code
31a90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
31aa0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20  LITE_NOMEM] and 
31ab0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65  an appropriate e
31ac0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
31ad0 0a 2a 2a 20 7b 48 31 36 34 32 34 7d 20 54 68 65  .** {H16424} The
31ae0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
31af0 5f 65 72 72 6f 72 5f 63 6f 64 65 28 43 2c 45 29  _error_code(C,E)
31b00 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
31b10 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
31b20 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
31b30 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
31b40 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65   C to be an exce
31b50 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72  ption with error
31b60 20 63 6f 64 65 20 45 2e 0a 2a 2a 20 20 20 20 20   code E..**     
31b70 20 20 20 20 20 54 68 65 20 65 72 72 6f 72 20 6d       The error m
31b80 65 73 73 61 67 65 20 74 65 78 74 20 69 73 20 75  essage text is u
31b90 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20  nchanged..**.** 
31ba0 7b 48 31 36 34 32 37 7d 20 54 68 65 20 5b 73 71  {H16427} The [sq
31bb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
31bc0 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,V)] interface
31bd0 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
31be0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
31bf0 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
31c00 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 33 32  n C to be the 32
31c10 2d 62 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c  -bit integer val
31c20 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ue V..**.** {H16
31c30 34 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  430} The [sqlite
31c40 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 43  3_result_int64(C
31c50 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,V)] interface c
31c60 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
31c70 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
31c80 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
31c90 43 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62  C to be the 64-b
31ca0 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  it integer value
31cb0 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33   V..**.** {H1643
31cc0 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
31cd0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20  result_null(C)] 
31ce0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
31cf0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
31d00 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
31d10 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
31d20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b  be NULL..**.** {
31d30 48 31 36 34 33 36 7d 20 54 68 65 20 5b 73 71 6c  H16436} The [sql
31d40 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
31d50 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72  (C,V,N,D)] inter
31d60 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
31d70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
31d80 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
31d90 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
31da0 65 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  e UTF-8 string.*
31db0 2a 20 20 20 20 20 20 20 20 20 20 56 20 75 70 20  *          V up 
31dc0 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
31dd0 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69  o if N is negati
31de0 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ve.**          o
31df0 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79  r the first N by
31e00 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73  tes of V if N is
31e10 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a   non-negative..*
31e20 2a 0a 2a 2a 20 7b 48 31 36 34 33 39 7d 20 54 68  *.** {H16439} Th
31e30 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
31e40 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
31e50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
31e60 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
31e70 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
31e80 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
31e90 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d 31 36  to be the UTF-16
31ea0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
31eb0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  er.**          s
31ec0 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68  tring V up to th
31ed0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20  e first zero if 
31ee0 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a  N is negative.**
31ef0 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65            or the
31f00 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f   first N bytes o
31f10 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d  f V if N is non-
31f20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  negative..**.** 
31f30 7b 48 31 36 34 34 32 7d 20 54 68 65 20 5b 73 71  {H16442} The [sq
31f40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
31f50 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 20  t16be(C,V,N,D)] 
31f60 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
31f70 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
31f80 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
31f90 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
31fa0 62 65 20 74 68 65 20 55 54 46 2d 31 36 20 62 69  be the UTF-16 bi
31fb0 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20  g-endian.**     
31fc0 20 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70       string V up
31fd0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
31fe0 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74  ro if N is negat
31ff0 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
32000 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62  or the first N b
32010 79 74 65 73 20 6f 72 20 56 20 69 66 20 4e 20 69  ytes or V if N i
32020 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a  s non-negative..
32030 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 35 7d 20 54  **.** {H16445} T
32040 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
32050 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c  lt_text16le(C,V,
32060 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  N,D)] interface 
32070 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
32080 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
32090 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
320a0 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46   C to be the UTF
320b0 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  -16 little-endia
320c0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  n.**          st
320d0 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65  ring V up to the
320e0 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e   first zero if N
320f0 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20   is negative.** 
32100 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
32110 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66  first N bytes of
32120 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e   V if N is non-n
32130 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
32140 48 31 36 34 34 38 7d 20 54 68 65 20 5b 73 71 6c  H16448} The [sql
32150 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
32160 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63  e(C,V)] interfac
32170 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
32180 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
32190 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
321a0 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 5b  on C to be the [
321b0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
321c0 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 20 20  te3_value].**   
321d0 20 20 20 20 20 20 20 6f 62 6a 65 63 74 20 56 2e         object V.
321e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 31 7d 20  .**.** {H16451} 
321f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
32200 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e  ult_zeroblob(C,N
32210 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
32220 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
32230 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
32240 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
32250 74 6f 20 62 65 20 61 6e 20 4e 2d 62 79 74 65 20  to be an N-byte 
32260 42 4c 4f 42 20 6f 66 20 61 6c 6c 20 7a 65 72 6f  BLOB of all zero
32270 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 34  s..**.** {H16454
32280 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
32290 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 5d 20 61  esult_error()] a
322a0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
322b0 6c 74 5f 65 72 72 6f 72 31 36 28 29 5d 0a 2a 2a  lt_error16()].**
322c0 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
322d0 61 63 65 73 20 6d 61 6b 65 20 61 20 63 6f 70 79  aces make a copy
322e0 20 6f 66 20 74 68 65 69 72 20 65 72 72 6f 72 20   of their error 
322f0 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20  message strings 
32300 62 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20  before.**       
32310 20 20 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a     returning..**
32320 0a 2a 2a 20 7b 48 31 36 34 35 37 7d 20 49 66 20  .** {H16457} If 
32330 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72  the D destructor
32340 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
32350 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
32360 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  ob(C,V,N,D)],.**
32370 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
32380 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43  e3_result_text(C
32390 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74  ,V,N,D)], [sqlit
323a0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
323b0 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20  (C,V,N,D)],.**  
323c0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
323d0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
323e0 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a  (C,V,N,D)], or.*
323f0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
32400 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
32410 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73  6le(C,V,N,D)] is
32420 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 20 5b 53   the constant [S
32430 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 0a 2a 2a  QLITE_STATIC].**
32440 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 6e            then n
32450 6f 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  o destructor is 
32460 65 76 65 72 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ever called on t
32470 68 65 20 70 6f 69 6e 74 65 72 20 56 20 61 6e 64  he pointer V and
32480 20 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20   SQLite.**      
32490 20 20 20 20 61 73 73 75 6d 65 73 20 74 68 61 74      assumes that
324a0 20 56 20 69 73 20 69 6d 6d 75 74 61 62 6c 65 2e   V is immutable.
324b0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36 30 7d 20  .**.** {H16460} 
324c0 49 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63  If the D destruc
324d0 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f  tor parameter to
324e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
324f0 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c  _blob(C,V,N,D)],
32500 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
32510 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
32520 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71  t(C,V,N,D)], [sq
32530 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
32540 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a  t16(C,V,N,D)],.*
32550 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
32560 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
32570 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f  6be(C,V,N,D)], o
32580 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
32590 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
325a0 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d  xt16le(C,V,N,D)]
325b0 20 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   is the constant
325c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
325d0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20  LITE_TRANSIENT] 
325e0 74 68 65 6e 20 74 68 65 20 69 6e 74 65 72 66 61  then the interfa
325f0 63 65 73 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ces makes a copy
32600 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
32610 20 20 20 20 63 6f 6e 74 65 6e 74 20 6f 66 20 56      content of V
32620 20 61 6e 64 20 72 65 74 61 69 6e 73 20 74 68 65   and retains the
32630 20 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   copy..**.** {H1
32640 36 34 36 33 7d 20 49 66 20 74 68 65 20 44 20 64  6463} If the D d
32650 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65  estructor parame
32660 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
32670 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c  result_blob(C,V,
32680 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  N,D)],.**       
32690 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
326a0 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29  lt_text(C,V,N,D)
326b0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ], [sqlite3_resu
326c0 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c  lt_text16(C,V,N,
326d0 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
326e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
326f0 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c  _text16be(C,V,N,
32700 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
32710 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
32720 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56  ult_text16le(C,V
32730 2c 4e 2c 44 29 5d 20 69 73 20 73 6f 6d 65 20 76  ,N,D)] is some v
32740 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a  alue other than.
32750 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
32760 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54  constants [SQLIT
32770 45 5f 53 54 41 54 49 43 5d 20 61 6e 64 20 5b 53  E_STATIC] and [S
32780 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
32790 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
327a0 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e    SQLite will in
327b0 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
327c0 74 6f 72 20 44 20 77 69 74 68 20 56 20 61 73 20  tor D with V as 
327d0 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e  its only argumen
327e0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  t.**          wh
327f0 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  en it has finish
32800 65 64 20 77 69 74 68 20 74 68 65 20 56 20 76 61  ed with the V va
32810 6c 75 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  lue..*/.void sql
32820 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
32830 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32840 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
32850 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
32860 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
32870 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
32880 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32890 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64  *, double);.void
328a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
328b0 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f  error(sqlite3_co
328c0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
328d0 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  ar*, int);.void 
328e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
328f0 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63  rror16(sqlite3_c
32900 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
32910 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
32920 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32930 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c  error_toobig(sql
32940 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
32950 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32960 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
32970 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32980 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
32990 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
329a0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
329b0 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
329c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
329d0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
329e0 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  t*, int);.void s
329f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
32a00 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t64(sqlite3_cont
32a10 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ext*, sqlite3_in
32a20 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t64);.void sqlit
32a30 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73  e3_result_null(s
32a40 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
32a50 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
32a60 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74  esult_text(sqlit
32a70 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
32a80 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76  st char*, int, v
32a90 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
32aa0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32ab0 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ult_text16(sqlit
32ac0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
32ad0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
32ae0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
32af0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32b00 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  ult_text16le(sql
32b10 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
32b20 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
32b30 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
32b40 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
32b50 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71  sult_text16be(sq
32b60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
32b70 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
32b80 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
32b90 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
32ba0 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69  esult_value(sqli
32bb0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
32bc0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76  lite3_value*);.v
32bd0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
32be0 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  lt_zeroblob(sqli
32bf0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
32c00 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
32c10 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65  I3REF: Define Ne
32c20 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75  w Collating Sequ
32c30 65 6e 63 65 73 20 7b 48 31 36 36 30 30 7d 20 3c  ences {H16600} <
32c40 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20300>.**.** Th
32c50 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
32c60 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65  e used to add ne
32c70 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  w collation sequ
32c80 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  ences to the.** 
32c90 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
32ca0 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
32cb0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
32cc0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ument..**.** The
32cd0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77   name of the new
32ce0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
32cf0 6e 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64  nce is specified
32d00 20 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   as a UTF-8 stri
32d10 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65  ng.** for sqlite
32d20 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
32d30 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  on() and sqlite3
32d40 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
32d50 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20  n_v2().** and a 
32d60 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f  UTF-16 string fo
32d70 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
32d80 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20  _collation16(). 
32d90 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20  In all cases.** 
32da0 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73  the name is pass
32db0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
32dc0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
32dd0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  nt..**.** The th
32de0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79  ird argument may
32df0 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   be one of the c
32e00 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45  onstants [SQLITE
32e10 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _UTF8],.** [SQLI
32e20 54 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b  TE_UTF16LE] or [
32e30 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
32e40 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
32e50 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69   the user-suppli
32e60 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78  ed.** routine ex
32e70 70 65 63 74 73 20 74 6f 20 62 65 20 70 61 73 73  pects to be pass
32e80 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  ed pointers to s
32e90 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75  trings encoded u
32ea0 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55  sing UTF-8,.** U
32eb0 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64  TF-16 little-end
32ec0 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
32ed0 69 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig-endian, respe
32ee0 63 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20  ctively. The.** 
32ef0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d  third argument m
32f00 69 67 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51  ight also be [SQ
32f10 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
32f20 45 44 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ED] to indicate 
32f30 74 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f 75 74  that.** the rout
32f40 69 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69 6e  ine expects poin
32f50 74 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20 77  ters to 16-bit w
32f60 6f 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72 69  ord aligned stri
32f70 6e 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36  ngs.** of UTF-16
32f80 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
32f90 79 74 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  yte order of the
32fa0 20 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a   host computer..
32fb0 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  **.** A pointer 
32fc0 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70 70  to the user supp
32fd0 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73  lied routine mus
32fe0 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  t be passed as t
32ff0 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75  he fifth.** argu
33000 6d 65 6e 74 2e 20 20 49 66 20 69 74 20 69 73 20  ment.  If it is 
33010 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68  NULL, this is th
33020 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69  e same as deleti
33030 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  ng the collation
33040 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f  .** sequence (so
33050 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
33060 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d  not call it anym
33070 6f 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74 69  ore)..** Each ti
33080 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  me the applicati
33090 6f 6e 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63  on supplied func
330a0 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c  tion is invoked,
330b0 20 69 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a   it is passed.**
330c0 20 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61   as its first pa
330d0 72 61 6d 65 74 65 72 20 61 20 63 6f 70 79 20 6f  rameter a copy o
330e0 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73  f the void* pass
330f0 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68  ed as the fourth
33100 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
33110 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
33120 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73 71  ollation() or sq
33130 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33140 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a  lation16()..**.*
33150 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
33160 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
33170 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
33180 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72  plied routine ar
33190 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a  e two strings,.*
331a0 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 6e 74  * each represent
331b0 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c  ed by a (length,
331c0 20 64 61 74 61 29 20 70 61 69 72 20 61 6e 64 20   data) pair and 
331d0 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65  encoded in the e
331e0 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20  ncoding.** that 
331f0 77 61 73 20 70 61 73 73 65 64 20 61 73 20 74 68  was passed as th
33200 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
33210 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   when the collat
33220 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73  ion sequence was
33230 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20  .** registered. 
33240 7b 45 4e 44 7d 20 20 54 68 65 20 61 70 70 6c 69  {END}  The appli
33250 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63  cation defined c
33260 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  ollation routine
33270 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
33280 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f  n negative, zero
33290 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 20   or positive if 
332a0 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67  the first string
332b0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a   is less than,.*
332c0 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  * equal to, or g
332d0 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
332e0 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69  second string. i
332f0 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53  .e. (STRING1 - S
33300 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54  TRING2)..**.** T
33310 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
33320 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
33330 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
33340 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
33350 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  tion().** except
33360 20 74 68 61 74 20 69 74 20 74 61 6b 65 73 20 61   that it takes a
33370 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74  n extra argument
33380 20 77 68 69 63 68 20 69 73 20 61 20 64 65 73 74   which is a dest
33390 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68  ructor for.** th
333a0 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68  e collation.  Th
333b0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
333c0 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
333d0 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  collation is.** 
333e0 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73  destroyed and is
333f0 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f   passed a copy o
33400 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
33410 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69  ameter void* poi
33420 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73  nter.** of the s
33430 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
33440 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a  llation_v2()..**
33450 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20   Collations are 
33460 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20 74  destroyed when t
33470 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64  hey are overridd
33480 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c  en by later call
33490 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c  s to the.** coll
334a0 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66  ation creation f
334b0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e  unctions or when
334c0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
334d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c  onnection] is cl
334e0 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  osed.** using [s
334f0 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e  qlite3_close()].
33500 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
33510 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 33  S:.**.** {H16603
33520 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
33530 61 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  all to the.**   
33540 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
33550 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33560 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
33570 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20  ] interface.**  
33580 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
33590 73 20 66 75 6e 63 74 69 6f 6e 20 46 20 61 73 20  s function F as 
335a0 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66  the comparison f
335b0 75 6e 63 74 69 6f 6e 20 75 73 65 64 20 74 6f 0a  unction used to.
335c0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6d 70 6c  **          impl
335d0 65 6d 65 6e 74 20 63 6f 6c 6c 61 74 69 6f 6e 20  ement collation 
335e0 58 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  X on the [databa
335f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42  se connection] B
33600 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
33610 20 64 61 74 61 62 61 73 65 73 20 68 61 76 69 6e   databases havin
33620 67 20 65 6e 63 6f 64 69 6e 67 20 45 2e 0a 2a 2a  g encoding E..**
33630 0a 2a 2a 20 7b 48 31 36 36 30 34 7d 20 53 51 4c  .** {H16604} SQL
33640 69 74 65 20 75 6e 64 65 72 73 74 61 6e 64 73 20  ite understands 
33650 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20  the X parameter 
33660 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
33670 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
33680 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c  ollation_v2(B,X,
33690 45 2c 50 2c 46 2c 44 29 5d 20 61 73 20 61 20 7a  E,P,F,D)] as a z
336a0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
336b0 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38  *          UTF-8
336c0 20 73 74 72 69 6e 67 20 69 6e 20 77 68 69 63 68   string in which
336d0 20 63 61 73 65 20 69 73 20 69 67 6e 6f 72 65 64   case is ignored
336e0 20 66 6f 72 20 41 53 43 49 49 20 63 68 61 72 61   for ASCII chara
336f0 63 74 65 72 73 20 61 6e 64 0a 2a 2a 20 20 20 20  cters and.**    
33700 20 20 20 20 20 20 69 73 20 73 69 67 6e 69 66 69        is signifi
33710 63 61 6e 74 20 66 6f 72 20 6e 6f 6e 2d 41 53 43  cant for non-ASC
33720 49 49 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  II characters..*
33730 2a 0a 2a 2a 20 7b 48 31 36 36 30 36 7d 20 53 75  *.** {H16606} Su
33740 63 63 65 73 73 69 76 65 20 63 61 6c 6c 73 20 74  ccessive calls t
33750 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
33760 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42  e_collation_v2(B
33770 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20  ,X,E,P,F,D)].** 
33780 20 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68           with th
33790 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20 66 6f  e same values fo
337a0 72 20 42 2c 20 58 2c 20 61 6e 64 20 45 2c 20 6f  r B, X, and E, o
337b0 76 65 72 72 69 64 65 20 70 72 69 6f 72 20 76 61  verride prior va
337c0 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  lues.**         
337d0 20 6f 66 20 50 2c 20 46 2c 20 61 6e 64 20 44 2e   of P, F, and D.
337e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 39 7d 20  .**.** {H16609} 
337f0 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
33800 72 20 44 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  r D in [sqlite3_
33810 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33820 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
33830 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  ].**          is
33840 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 69   not NULL then i
33850 74 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  t is called with
33860 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e   argument P when
33870 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
33880 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
33890 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 62  ion is dropped b
338a0 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  y SQLite..**.** 
338b0 7b 48 31 36 36 31 32 7d 20 41 20 63 6f 6c 6c 61  {H16612} A colla
338c0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
338d0 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20 69 74   dropped when it
338e0 20 69 73 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a   is overloaded..
338f0 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 35 7d 20 41  **.** {H16615} A
33900 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
33910 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77  ion is dropped w
33920 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
33930 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20   connection.**  
33940 20 20 20 20 20 20 20 20 69 73 20 63 6c 6f 73 65          is close
33950 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
33960 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
33970 20 7b 48 31 36 36 31 38 7d 20 54 68 65 20 70 6f   {H16618} The po
33980 69 6e 74 65 72 20 50 20 69 6e 20 5b 73 71 6c 69  inter P in [sqli
33990 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
339a0 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c  tion_v2(B,X,E,P,
339b0 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  F,D)].**        
339c0 20 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f    is passed thro
339d0 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
339e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
339f0 65 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20  e comparison.** 
33a00 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f           functio
33a10 6e 20 46 20 66 6f 72 20 61 6c 6c 20 73 75 62 73  n F for all subs
33a20 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
33a30 6e 73 20 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b  ns of F..**.** {
33a40 48 31 36 36 32 31 7d 20 41 20 63 61 6c 6c 20 74  H16621} A call t
33a50 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
33a60 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c  e_collation(B,X,
33a70 45 2c 50 2c 46 29 5d 20 69 73 20 65 78 61 63 74  E,P,F)] is exact
33a80 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ly.**          t
33a90 68 65 20 73 61 6d 65 20 61 73 20 61 20 63 61 6c  he same as a cal
33aa0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  l to [sqlite3_cr
33ab0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
33ac0 32 28 29 5d 20 77 69 74 68 0a 2a 2a 20 20 20 20  2()] with.**    
33ad0 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 70        the same p
33ae0 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 61 20  arameters and a 
33af0 4e 55 4c 4c 20 64 65 73 74 72 75 63 74 6f 72 2e  NULL destructor.
33b00 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 34 7d 20  .**.** {H16624} 
33b10 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 5b 73 71 6c  Following a [sql
33b20 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
33b30 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
33b40 2c 46 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,F,D)],.**      
33b50 20 20 20 20 53 51 4c 69 74 65 20 75 73 65 73 20      SQLite uses 
33b60 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66  the comparison f
33b70 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c  unction F for al
33b80 6c 20 74 65 78 74 20 63 6f 6d 70 61 72 69 73 6f  l text compariso
33b90 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 70  n.**          op
33ba0 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
33bb0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
33bc0 74 69 6f 6e 5d 20 42 20 6f 6e 20 74 65 78 74 20  tion] B on text 
33bd0 76 61 6c 75 65 73 20 74 68 61 74 0a 2a 2a 20 20  values that.**  
33be0 20 20 20 20 20 20 20 20 75 73 65 20 74 68 65 20          use the 
33bf0 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e  collating sequen
33c00 63 65 20 6e 61 6d 65 64 20 58 2e 0a 2a 2a 0a 2a  ce named X..**.*
33c10 2a 20 7b 48 31 36 36 32 37 7d 20 54 68 65 20 5b  * {H16627} The [
33c20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
33c30 6f 6c 6c 61 74 69 6f 6e 31 36 28 42 2c 58 2c 45  ollation16(B,X,E
33c40 2c 50 2c 46 29 5d 20 77 6f 72 6b 73 20 74 68 65  ,P,F)] works the
33c50 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   same.**        
33c60 20 20 61 73 20 5b 73 71 6c 69 74 65 33 5f 63 72    as [sqlite3_cr
33c70 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42  eate_collation(B
33c80 2c 58 2c 45 2c 50 2c 46 29 5d 20 65 78 63 65 70  ,X,E,P,F)] excep
33c90 74 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20  t that the.**   
33ca0 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e         collation
33cb0 20 6e 61 6d 65 20 58 20 69 73 20 75 6e 64 65 72   name X is under
33cc0 73 74 6f 6f 64 20 61 73 20 55 54 46 2d 31 36 20  stood as UTF-16 
33cd0 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
33ce0 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rder.**         
33cf0 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d   instead of UTF-
33d00 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 33 30  8..**.** {H16630
33d10 7d 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20  } When multiple 
33d20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
33d30 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62  ions are availab
33d40 6c 65 20 66 6f 72 20 74 68 65 20 73 61 6d 65 0a  le for the same.
33d50 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c  **          coll
33d60 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 2c 20  ating sequence, 
33d70 53 51 4c 69 74 65 20 63 68 6f 6f 73 65 73 20 74  SQLite chooses t
33d80 68 65 20 6f 6e 65 20 77 68 6f 73 65 20 74 65 78  he one whose tex
33d90 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 20 20  t encoding.**   
33da0 20 20 20 20 20 20 20 72 65 71 75 69 72 65 73 20         requires 
33db0 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
33dc0 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66   of conversion f
33dd0 72 6f 6d 20 74 68 65 20 64 65 66 61 75 6c 74 0a  rom the default.
33de0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74  **          text
33df0 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65   encoding of the
33e00 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e   database..*/.in
33e10 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
33e20 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71  _collation(.  sq
33e30 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
33e40 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
33e50 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
33e60 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
33e70 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
33e80 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
33e90 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
33ea0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
33eb0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33ec0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  _v2(.  sqlite3*,
33ed0 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
33ee0 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
33ef0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a  extRep, .  void*
33f00 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
33f10 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
33f20 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
33f30 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69  st void*),.  voi
33f40 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
33f50 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
33f60 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
33f70 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
33f80 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  *, .  const void
33f90 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65   *zName,.  int e
33fa0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
33fb0 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
33fc0 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
33fd0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
33fe0 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
33ff0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
34000 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20  ollation Needed 
34010 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 36 37 30  Callbacks {H1670
34020 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a  0} <S20300>.**.*
34030 2a 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e  * To avoid havin
34040 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c  g to register al
34050 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  l collation sequ
34060 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64  ences before a d
34070 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62  atabase.** can b
34080 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65  e used, a single
34090 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
340a0 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
340b0 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  ered with the.**
340c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
340d0 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63 61 6c  ction] to be cal
340e0 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20  led whenever an 
340f0 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
34100 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
34110 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  is required..**.
34120 2a 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74 69  ** If the functi
34130 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64  on is registered
34140 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
34150 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
34160 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68  ded() API,.** th
34170 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20  en it is passed 
34180 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64  the names of und
34190 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
341a0 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74   sequences as st
341b0 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64  rings.** encoded
341c0 20 69 6e 20 55 54 46 2d 38 2e 20 7b 48 31 36 37   in UTF-8. {H167
341d0 30 33 7d 20 49 66 20 73 71 6c 69 74 65 33 5f 63  03} If sqlite3_c
341e0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
341f0 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20  6() is used,.** 
34200 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61  the names are pa
34210 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  ssed as UTF-16 i
34220 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65  n machine native
34230 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20   byte order..** 
34240 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  A call to either
34250 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63   function replac
34260 65 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67 20  es any existing 
34270 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
34280 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
34290 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68  k is invoked, th
342a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
342b0 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70   passed is a cop
342c0 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f  y.** of the seco
342d0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
342e0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
342f0 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20  _needed() or.** 
34300 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
34310 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54  n_needed16().  T
34320 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
34330 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61  nt is the databa
34340 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
34350 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
34360 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
34370 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b  [SQLITE_UTF8], [
34380 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
34390 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
343a0 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74  TF16LE], indicat
343b0 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73  ing the most des
343c0 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74  irable form of t
343d0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
343e0 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f  sequence functio
343f0 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65  n required.  The
34400 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
34410 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
34420 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64   the.** required
34430 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
34440 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  nce..**.** The c
34450 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
34460 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72   should register
34470 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
34480 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  lation using.** 
34490 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
344a0 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73  collation()], [s
344b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
344c0 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  llation16()], or
344d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
344e0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
344f0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
34500 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
34510 36 37 30 32 7d 20 41 20 73 75 63 63 65 73 73 66  6702} A successf
34520 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
34530 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
34540 65 64 65 64 28 44 2c 50 2c 46 29 5d 0a 2a 2a 20  eded(D,P,F)].** 
34550 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
34560 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
34570 65 65 64 65 64 31 36 28 44 2c 50 2c 46 29 5d 20  eeded16(D,P,F)] 
34580 63 61 75 73 65 73 0a 2a 2a 20 20 20 20 20 20 20  causes.**       
34590 20 20 20 74 68 65 20 5b 64 61 74 61 62 61 73 65     the [database
345a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74   connection] D t
345b0 6f 20 69 6e 76 6f 6b 65 20 63 61 6c 6c 62 61 63  o invoke callbac
345c0 6b 20 46 20 77 69 74 68 20 66 69 72 73 74 0a 2a  k F with first.*
345d0 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
345e0 65 74 65 72 20 50 20 77 68 65 6e 65 76 65 72 20  eter P whenever 
345f0 69 74 20 6e 65 65 64 73 20 61 20 63 6f 6d 70 61  it needs a compa
34600 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 66  rison function f
34610 6f 72 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  or a.**         
34620 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65   collating seque
34630 6e 63 65 20 74 68 61 74 20 69 74 20 64 6f 65 73  nce that it does
34640 20 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f 75 74 2e   not know about.
34650 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 34 7d 20  .**.** {H16704} 
34660 45 61 63 68 20 73 75 63 63 65 73 73 66 75 6c 20  Each successful 
34670 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
34680 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
34690 64 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  d()] or.**      
346a0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
346b0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
346c0 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  )] overrides the
346d0 20 63 61 6c 6c 62 61 63 6b 20 72 65 67 69 73 74   callback regist
346e0 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ered.**         
346f0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
34700 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34710 6e 5d 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c  n] by prior call
34720 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 20  s to either.**  
34730 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
34740 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 36  e..**.** {H16706
34750 7d 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  } The name of th
34760 65 20 72 65 71 75 65 73 74 65 64 20 63 6f 6c 6c  e requested coll
34770 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  ating function p
34780 61 73 73 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  assed in the.** 
34790 20 20 20 20 20 20 20 20 20 34 74 68 20 70 61 72           4th par
347a0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
347b0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 20 55 54 46  llback is in UTF
347c0 2d 38 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61  -8 if the callba
347d0 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  ck.**          w
347e0 61 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73  as registered us
347f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  ing [sqlite3_col
34800 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
34810 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
34820 20 69 73 20 69 6e 20 55 54 46 2d 31 36 20 6e 61   is in UTF-16 na
34830 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
34840 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  if the callback 
34850 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  was.**          
34860 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
34870 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
34880 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e  ion_needed16()].
34890 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
348a0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
348b0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
348c0 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28   void*, .  void(
348d0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
348e0 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
348f0 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69  onst char*).);.i
34900 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
34910 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20  tion_needed16(. 
34920 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
34930 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76  id*,.  void(*)(v
34940 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
34950 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
34960 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
34970 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65  * Specify the ke
34980 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74  y for an encrypt
34990 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68  ed database.  Th
349a0 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  is routine shoul
349b0 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72  d be.** called r
349c0 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74  ight after sqlit
349d0 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a  e3_open()..**.**
349e0 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
349f0 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
34a00 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
34a10 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
34a20 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
34a30 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
34a40 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74  te3_key(.  sqlit
34a50 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
34a60 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
34a70 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
34a80 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
34a90 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
34aa0 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b  Key     /* The k
34ab0 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
34ac0 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f  Change the key o
34ad0 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  n an open databa
34ae0 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72  se.  If the curr
34af0 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20  ent database is 
34b00 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64  not.** encrypted
34b10 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  , this routine w
34b20 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20  ill encrypt it. 
34b30 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e   If pNew==0 or n
34b40 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64  New==0, the.** d
34b50 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79  atabase is decry
34b60 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  pted..**.** The 
34b70 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
34b80 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
34b90 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
34ba0 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
34bb0 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
34bc0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
34bd0 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  ekey(.  sqlite3 
34be0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
34bf0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
34c00 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
34c10 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
34c20 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
34c30 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20       /* The new 
34c40 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
34c50 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65   CAPI3REF: Suspe
34c60 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72  nd Execution For
34c70 20 41 20 53 68 6f 72 74 20 54 69 6d 65 20 7b 48   A Short Time {H
34c80 31 30 35 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  10530}.**.** The
34c90 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29   sqlite3_sleep()
34ca0 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
34cb0 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72   the current thr
34cc0 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65  ead to suspend e
34cd0 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20  xecution.** for 
34ce0 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65  at least a numbe
34cf0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
34d00 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69  s specified in i
34d10 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ts parameter..**
34d20 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61  .** If the opera
34d30 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73  ting system does
34d40 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65   not support sle
34d50 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68  ep requests with
34d60 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20  .** millisecond 
34d70 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  time resolution,
34d80 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77   then the time w
34d90 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75  ill be rounded u
34da0 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72  p to.** the near
34db0 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20  est second. The 
34dc0 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
34dd0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20  econds of sleep 
34de0 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75  actually.** requ
34df0 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f  ested from the o
34e00 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
34e10 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
34e20 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  ** SQLite implem
34e30 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66  ents this interf
34e40 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74  ace by calling t
34e50 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d  he xSleep().** m
34e60 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
34e70 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
34e80 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  s] object..**.**
34e90 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
34ea0 2a 2a 20 7b 48 31 30 35 33 33 7d 20 54 68 65 20  ** {H10533} The 
34eb0 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d  [sqlite3_sleep(M
34ec0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 6e 76  )] interface inv
34ed0 6f 6b 65 73 20 74 68 65 20 78 53 6c 65 65 70 0a  okes the xSleep.
34ee0 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 74 68  **          meth
34ef0 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
34f00 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 7c 56  t [sqlite3_vfs|V
34f10 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a  FS] in order to.
34f20 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75 73 70  **          susp
34f30 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  end execution of
34f40 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72   the current thr
34f50 65 61 64 20 66 6f 72 20 61 74 20 6c 65 61 73 74  ead for at least
34f60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4d 20 6d  .**          M m
34f70 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a 0a  illiseconds..**.
34f80 2a 2a 20 7b 48 31 30 35 33 36 7d 20 54 68 65 20  ** {H10536} The 
34f90 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d  [sqlite3_sleep(M
34fa0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
34fb0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
34fc0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  of.**          m
34fd0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
34fe0 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20 72 65  leep actually re
34ff0 71 75 65 73 74 65 64 20 6f 66 20 74 68 65 20 6f  quested of the o
35000 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20 20 20 20  perating.**     
35010 20 20 20 20 20 73 79 73 74 65 6d 2c 20 77 68 69       system, whi
35020 63 68 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67  ch might be larg
35030 65 72 20 74 68 61 6e 20 74 68 65 20 70 61 72 61  er than the para
35040 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74 20  meter M..*/.int 
35050 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e  sqlite3_sleep(in
35060 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
35070 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65  REF: Name Of The
35080 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20   Folder Holding 
35090 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 20  Temporary Files 
350a0 7b 48 31 30 33 31 30 7d 0a 2a 2a 0a 2a 2a 20 49  {H10310}.**.** I
350b0 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61  f this global va
350c0 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74  riable is made t
350d0 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  o point to a str
350e0 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20  ing which is.** 
350f0 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f  the name of a fo
35100 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72  lder (a.k.a. dir
35110 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c  ectory), then al
35120 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  l temporary file
35130 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  s.** created by 
35140 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 70  SQLite will be p
35150 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69  laced in that di
35160 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68 69  rectory.  If thi
35170 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73  s variable.** is
35180 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
35190 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72   then SQLite per
351a0 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66  forms a search f
351b0 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  or an appropriat
351c0 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
351d0 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ile directory..*
351e0 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  *.** It is not s
351f0 61 66 65 20 74 6f 20 6d 6f 64 69 66 79 20 74 68  afe to modify th
35200 69 73 20 76 61 72 69 61 62 6c 65 20 6f 6e 63 65  is variable once
35210 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
35220 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 68 61 73 20  nection].** has 
35230 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 20 49 74  been opened.  It
35240 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61   is intended tha
35250 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
35260 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61  be set once.** a
35270 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73  s part of proces
35280 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
35290 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20   and before any 
352a0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
352b0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76  .** routines hav
352c0 65 20 62 65 65 6e 20 63 61 6c 6c 20 61 6e 64 20  e been call and 
352d0 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
352e0 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2f 0a   thereafter..*/.
352f0 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68  SQLITE_EXTERN ch
35300 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70  ar *sqlite3_temp
35310 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a  _directory;../*.
35320 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73  ** CAPI3REF: Tes
35330 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69  t For Auto-Commi
35340 74 20 4d 6f 64 65 20 7b 48 31 32 39 33 30 7d 20  t Mode {H12930} 
35350 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S60200>.** KEYW
35360 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69  ORDS: {autocommi
35370 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68  t mode}.**.** Th
35380 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
35390 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72  tocommit() inter
353a0 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e  face returns non
353b0 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f  -zero or.** zero
353c0 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61   if the given da
353d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
353e0 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69  n is or is not i
353f0 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  n autocommit mod
35400 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  e,.** respective
35410 6c 79 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20  ly.  Autocommit 
35420 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65  mode is on by de
35430 66 61 75 6c 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f  fault..** Autoco
35440 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73  mmit mode is dis
35450 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49  abled by a [BEGI
35460 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  N] statement..**
35470 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
35480 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62   is re-enabled b
35490 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20  y a [COMMIT] or 
354a0 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a  [ROLLBACK]..**.*
354b0 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e  * If certain kin
354c0 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63  ds of errors occ
354d0 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e  ur on a statemen
354e0 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69  t within a multi
354f0 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72  -statement.** tr
35500 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72  ansaction (error
35510 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c  s including [SQL
35520 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49  ITE_FULL], [SQLI
35530 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53  TE_IOERR],.** [S
35540 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53  QLITE_NOMEM], [S
35550 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64  QLITE_BUSY], and
35560 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
35570 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a  PT]) then the.**
35580 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67   transaction mig
35590 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ht be rolled bac
355a0 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
355b0 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74    The only way t
355c0 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68  o.** find out wh
355d0 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74  ether SQLite aut
355e0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
355f0 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  d back the trans
35600 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20  action after.** 
35610 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75  an error is to u
35620 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  se this function
35630 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
35640 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33  TS:.**.** {H1293
35650 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
35660 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 44  get_autocommit(D
35670 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
35680 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72  urns non-zero or
35690 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
356a0 6f 20 69 66 20 74 68 65 20 5b 64 61 74 61 62 61  o if the [databa
356b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
356c0 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e   is or is not in
356d0 20 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 20   autocommit.**  
356e0 20 20 20 20 20 20 20 20 6d 6f 64 65 2c 20 72 65          mode, re
356f0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
35700 2a 20 7b 48 31 32 39 33 32 7d 20 41 75 74 6f 63  * {H12932} Autoc
35710 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e  ommit mode is on
35720 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
35730 2a 2a 20 7b 48 31 32 39 33 33 7d 20 41 75 74 6f  ** {H12933} Auto
35740 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64  commit mode is d
35750 69 73 61 62 6c 65 64 20 62 79 20 61 20 73 75 63  isabled by a suc
35760 63 65 73 73 66 75 6c 20 5b 42 45 47 49 4e 5d 20  cessful [BEGIN] 
35770 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
35780 20 7b 48 31 32 39 33 34 7d 20 41 75 74 6f 63 6f   {H12934} Autoco
35790 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 65 6e 61  mmit mode is ena
357a0 62 6c 65 64 20 62 79 20 61 20 73 75 63 63 65 73  bled by a succes
357b0 73 66 75 6c 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72  sful [COMMIT] or
357c0 20 5b 52 4f 4c 4c 42 41 43 4b 5d 0a 2a 2a 20 20   [ROLLBACK].**  
357d0 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e          statemen
357e0 74 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54  t..**.** ASSUMPT
357f0 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  IONS:.**.** {A12
35800 39 33 36 7d 20 49 66 20 61 6e 6f 74 68 65 72 20  936} If another 
35810 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74  thread changes t
35820 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74  he autocommit st
35830 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61  atus of the data
35840 62 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  base.**         
35850 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
35860 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
35870 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20  s running, then 
35880 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
35890 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
358a0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e  undefined..*/.in
358b0 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  t sqlite3_get_au
358c0 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33  tocommit(sqlite3
358d0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
358e0 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61  REF: Find The Da
358f0 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66  tabase Handle Of
35900 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
35910 65 6d 65 6e 74 20 7b 48 31 33 31 32 30 7d 0a 2a  ement {H13120}.*
35920 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
35930 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72  _db_handle inter
35940 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
35950 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35960 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a  ction] handle.**
35970 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65   to which a [pre
35980 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
35990 20 62 65 6c 6f 6e 67 73 2e 20 20 54 68 65 20 64   belongs.  The d
359a0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 72  atabase handle r
359b0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 73 71  eturned by.** sq
359c0 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
359d0 69 73 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  is the same data
359e0 62 61 73 65 20 68 61 6e 64 6c 65 20 74 68 61 74  base handle that
359f0 20 77 61 73 20 74 68 65 20 66 69 72 73 74 20 61   was the first a
35a00 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68  rgument.** to th
35a10 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
35a20 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f  re_v2()] call (o
35a30 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20  r its variants) 
35a40 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f  that was used to
35a50 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20 73  .** create the s
35a60 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
35a70 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 0a  first place..**.
35a80 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
35a90 2a 0a 2a 2a 20 7b 48 31 33 31 32 33 7d 20 54 68  *.** {H13123} Th
35aa0 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  e [sqlite3_db_ha
35ab0 6e 64 6c 65 28 53 29 5d 20 69 6e 74 65 72 66 61  ndle(S)] interfa
35ac0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
35ad0 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  nter.**         
35ae0 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
35af0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73  e connection] as
35b00 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
35b10 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
35b20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
35b30 74 5d 20 53 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  t] S..*/.sqlite3
35b40 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e   *sqlite3_db_han
35b50 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dle(sqlite3_stmt
35b60 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
35b70 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65  REF: Find the ne
35b80 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  xt prepared stat
35b90 65 6d 65 6e 74 20 7b 48 31 33 31 34 30 7d 0a 2a  ement {H13140}.*
35ba0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66  *.** This interf
35bb0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
35bc0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78  inter to the nex
35bd0 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  t [prepared stat
35be0 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20  ement] after.** 
35bf0 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64  pStmt associated
35c00 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
35c10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
35c20 70 44 62 2e 20 20 49 66 20 70 53 74 6d 74 20 69  pDb.  If pStmt i
35c30 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74  s NULL.** then t
35c40 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65  his interface re
35c50 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
35c60 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 65  to the first pre
35c70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
35c80 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
35c90 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  th the database 
35ca0 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20  connection pDb. 
35cb0 20 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20   If no prepared 
35cc0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74  statement.** sat
35cd0 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69  isfies the condi
35ce0 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f  tions of this ro
35cf0 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e  utine, it return
35d00 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e  s NULL..**.** IN
35d10 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
35d20 7b 48 31 33 31 34 33 7d 20 49 66 20 44 20 69 73  {H13143} If D is
35d30 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
35d40 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 68 6f  nection] that ho
35d50 6c 64 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  lds one or more.
35d60 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e 66 69  **          unfi
35d70 6e 61 6c 69 7a 65 64 20 5b 70 72 65 70 61 72 65  nalized [prepare
35d80 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e  d statements] an
35d90 64 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  d S is a NULL po
35da0 69 6e 74 65 72 2c 0a 2a 2a 20 20 20 20 20 20 20  inter,.**       
35db0 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33     then [sqlite3
35dc0 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29  _next_stmt(D, S)
35dd0 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20  ] routine shall 
35de0 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72  return a pointer
35df0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
35e00 6f 6e 65 20 6f 66 20 74 68 65 20 70 72 65 70 61  one of the prepa
35e10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61  red statements a
35e20 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 44  ssociated with D
35e30 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 36 7d  ..**.** {H13146}
35e40 20 49 66 20 44 20 69 73 20 61 20 5b 64 61 74 61   If D is a [data
35e50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
35e60 20 74 68 61 74 20 68 6f 6c 64 73 20 6e 6f 20 75   that holds no u
35e70 6e 66 69 6e 61 6c 69 7a 65 64 0a 2a 2a 20 20 20  nfinalized.**   
35e80 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
35e90 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64   statements] and
35ea0 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   S is a NULL poi
35eb0 6e 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  nter, then.**   
35ec0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
35ed0 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d  next_stmt(D, S)]
35ee0 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72   routine shall r
35ef0 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  eturn a NULL poi
35f00 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  nter..**.** {H13
35f10 31 34 39 7d 20 49 66 20 53 20 69 73 20 61 20 5b  149} If S is a [
35f20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
35f30 6e 74 5d 20 69 6e 20 74 68 65 20 5b 64 61 74 61  nt] in the [data
35f40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
35f50 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61   D.**          a
35f60 6e 64 20 53 20 69 73 20 6e 6f 74 20 74 68 65 20  nd S is not the 
35f70 6c 61 73 74 20 70 72 65 70 61 72 65 64 20 73 74  last prepared st
35f80 61 74 65 6d 65 6e 74 20 69 6e 20 44 2c 20 74 68  atement in D, th
35f90 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  en.**          [
35fa0 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
35fb0 74 28 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65  t(D, S)] routine
35fc0 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20   shall return a 
35fd0 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20  pointer.**      
35fe0 20 20 20 20 74 6f 20 74 68 65 20 6e 65 78 74 20      to the next 
35ff0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
36000 6e 74 20 69 6e 20 44 20 61 66 74 65 72 20 53 2e  nt in D after S.
36010 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 35 32 7d 20  .**.** {H13152} 
36020 49 66 20 53 20 69 73 20 74 68 65 20 6c 61 73 74  If S is the last
36030 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
36040 6d 65 6e 74 5d 20 69 6e 20 74 68 65 0a 2a 2a 20  ment] in the.** 
36050 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
36060 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
36070 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   then the [sqlit
36080 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20  e3_next_stmt(D, 
36090 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  S)].**          
360a0 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65  routine shall re
360b0 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  turn a NULL poin
360c0 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  ter..*/.sqlite3_
360d0 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65  stmt *sqlite3_ne
360e0 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20  xt_stmt(sqlite3 
360f0 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74  *pDb, sqlite3_st
36100 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
36110 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
36120 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b  mit And Rollback
36130 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61   Notification Ca
36140 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 35 30 7d  llbacks {H12950}
36150 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S60400>.**.** 
36160 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  The sqlite3_comm
36170 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  it_hook() interf
36180 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
36190 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
361a0 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
361b0 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72  ed whenever a tr
361c0 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d  ansaction is com
361d0 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63  mitted..** Any c
361e0 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
361f0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
36200 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  o sqlite3_commit
36210 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
36220 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
36230 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
36240 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68  verridden..** Th
36250 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  e sqlite3_rollba
36260 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  ck_hook() interf
36270 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
36280 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
36290 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
362a0 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72  ed whenever a tr
362b0 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d  ansaction is com
362c0 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63  mitted..** Any c
362d0 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
362e0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
362f0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  o sqlite3_commit
36300 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
36310 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
36320 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
36330 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68  verridden..** Th
36340 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
36350 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
36360 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  h to the callbac
36370 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c  k..** If the cal
36380 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69  lback on a commi
36390 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20  t hook function 
363a0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
363b0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ,.** then the co
363c0 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65  mmit is converte
363d0 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63  d into a rollbac
363e0 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  k..**.** If anot
363f0 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73  her function was
36400 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69   previously regi
36410 73 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70  stered, its.** p
36420 41 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74  Arg value is ret
36430 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
36440 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  e NULL is return
36450 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  ed..**.** Regist
36460 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e  ering a NULL fun
36470 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74  ction disables t
36480 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  he callback..**.
36490 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f  ** For the purpo
364a0 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c  ses of this API,
364b0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
364c0 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62  s said to have b
364d0 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61  een.** rolled ba
364e0 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69  ck if an explici
364f0 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61  t "ROLLBACK" sta
36500 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74  tement is execut
36510 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72  ed, or.** an err
36520 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74  or or constraint
36530 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69   causes an impli
36540 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20  cit rollback to 
36550 6f 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f  occur..** The ro
36560 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20  llback callback 
36570 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69  is not invoked i
36580 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  f a transaction 
36590 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  is.** automatica
365a0 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
365b0 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61  because the data
365c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
365d0 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68  is closed..** Th
365e0 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62  e rollback callb
365f0 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
36600 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
36610 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64  ion is.** rolled
36620 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 61 20   back because a 
36630 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20  commit callback 
36640 72 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72  returned non-zer
36650 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65  o..** <todo> Che
36660 63 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64  ck on this </tod
36670 6f 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  o>.**.** INVARIA
36680 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  NTS:.**.** {H129
36690 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  51} The [sqlite3
366a0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46  _commit_hook(D,F
366b0 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,P)] interface r
366c0 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a 2a 20  egisters the.** 
366d0 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
366e0 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20  k function F to 
366f0 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
36700 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65  argument P whene
36710 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ver.**          
36720 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  a transaction co
36730 6d 6d 69 74 73 20 6f 6e 20 74 68 65 20 5b 64 61  mmits on the [da
36740 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36750 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  n] D..**.** {H12
36760 39 35 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  952} The [sqlite
36770 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c  3_commit_hook(D,
36780 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  F,P)] interface 
36790 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61 72  returns the P ar
367a0 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20  gument.**       
367b0 20 20 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76     from the prev
367c0 69 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 20 74  ious call with t
367d0 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
367e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
367f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
36800 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72 73  NULL on the firs
36810 74 20 63 61 6c 6c 20 66 6f 72 20 61 20 70 61 72  t call for a par
36820 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
36830 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a   connection D..*
36840 2a 0a 2a 2a 20 7b 48 31 32 39 35 33 7d 20 45 61  *.** {H12953} Ea
36850 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ch call to [sqli
36860 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
36870 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 68  )] overwrites th
36880 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  e callback.**   
36890 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
368a0 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73  d by prior calls
368b0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 34 7d  ..**.** {H12954}
368c0 20 49 66 20 74 68 65 20 46 20 61 72 67 75 6d 65   If the F argume
368d0 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  nt to [sqlite3_c
368e0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50  ommit_hook(D,F,P
368f0 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20  )] is NULL.**   
36900 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20         then the 
36910 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c  commit hook call
36920 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 65 64  back is canceled
36930 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b   and no callback
36940 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
36950 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 74  invoked when a t
36960 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69  ransaction commi
36970 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35  ts..**.** {H1295
36980 35 7d 20 49 66 20 74 68 65 20 63 6f 6d 6d 69 74  5} If the commit
36990 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
369a0 73 20 6e 6f 6e 2d 7a 65 72 6f 20 74 68 65 6e 20  s non-zero then 
369b0 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 0a 2a 2a  the commit is.**
369c0 20 20 20 20 20 20 20 20 20 20 63 6f 6e 76 65 72            conver
369d0 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62  ted into a rollb
369e0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ack..**.** {H129
369f0 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  61} The [sqlite3
36a00 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
36a10 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
36a20 20 72 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a   registers the.*
36a30 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
36a40 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74  ack function F t
36a50 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  o be invoked wit
36a60 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65  h argument P whe
36a70 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  never.**        
36a80 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20    a transaction 
36a90 72 6f 6c 6c 73 20 62 61 63 6b 20 6f 6e 20 74 68  rolls back on th
36aa0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
36ab0 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
36ac0 20 7b 48 31 32 39 36 32 7d 20 54 68 65 20 5b 73   {H12962} The [s
36ad0 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
36ae0 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
36af0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
36b00 68 65 20 50 0a 2a 2a 20 20 20 20 20 20 20 20 20  he P.**         
36b10 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74   argument from t
36b20 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
36b30 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 0a 2a   with the same.*
36b40 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
36b50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
36b60 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74   D, or NULL on t
36b70 68 65 20 66 69 72 73 74 20 63 61 6c 6c 0a 2a 2a  he first call.**
36b80 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 61 20            for a 
36b90 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
36ba0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
36bb0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 33 7d  ..**.** {H12963}
36bc0 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73   Each call to [s
36bd0 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
36be0 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69 74  hook()] overwrit
36bf0 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
36c00 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
36c10 73 74 65 72 65 64 20 62 79 20 70 72 69 6f 72 20  stered by prior 
36c20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  calls..**.** {H1
36c30 32 39 36 34 7d 20 49 66 20 74 68 65 20 46 20 61  2964} If the F a
36c40 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
36c50 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
36c60 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55 4c  k(D,F,P)] is NUL
36c70 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  L.**          th
36c80 65 6e 20 74 68 65 20 72 6f 6c 6c 62 61 63 6b 20  en the rollback 
36c90 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  hook callback is
36ca0 20 63 61 6e 63 65 6c 65 64 20 61 6e 64 20 6e 6f   canceled and no
36cb0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
36cc0 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64        is invoked
36cd0 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61 63 74   when a transact
36ce0 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 2e 0a  ion rolls back..
36cf0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
36d00 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c  _commit_hook(sql
36d10 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
36d20 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f  id*), void*);.vo
36d30 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  id *sqlite3_roll
36d40 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  back_hook(sqlite
36d50 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  3*, void(*)(void
36d60 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a   *), void*);../*
36d70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
36d80 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69  ta Change Notifi
36d90 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
36da0 20 7b 48 31 32 39 37 30 7d 20 3c 53 36 30 34 30   {H12970} <S6040
36db0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
36dc0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
36dd0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
36de0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
36df0 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  k function.** wi
36e00 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
36e10 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65   connection] ide
36e20 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ntified by the f
36e30 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
36e40 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
36e50 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73  henever a row is
36e60 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
36e70 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a  ed or deleted..*
36e80 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73  * Any callback s
36e90 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
36ea0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75   call to this fu
36eb0 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68  nction.** for th
36ec0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
36ed0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
36ee0 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20  erridden..**.** 
36ef0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
36f00 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
36f10 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   to the function
36f20 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20   to invoke when 
36f30 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61  a.** row is upda
36f40 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ted, inserted or
36f50 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 54 68 65   deleted..** The
36f60 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
36f70 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
36f80 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
36f90 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
36fa0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70  ** to sqlite3_up
36fb0 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20  date_hook()..** 
36fc0 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62  The second callb
36fd0 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ack argument is 
36fe0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
36ff0 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  NSERT], [SQLITE_
37000 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  DELETE],.** or [
37010 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20  SQLITE_UPDATE], 
37020 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
37030 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
37040 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62  caused the callb
37050 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76  ack.** to be inv
37060 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 74 68 69  oked..** The thi
37070 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72  rd and fourth ar
37080 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63  guments to the c
37090 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20  allback contain 
370a0 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 0a  pointers to the.
370b0 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  ** database and 
370c0 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61  table name conta
370d0 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63 74  ining the affect
370e0 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 68 65 20 66  ed row..** The f
370f0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61  inal callback pa
37100 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 72  rameter is the r
37110 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f 77 2e  owid of the row.
37120 20 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 0a   In the case of.
37130 2a 2a 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68  ** an update, th
37140 69 73 20 69 73 20 74 68 65 20 72 6f 77 69 64 20  is is the rowid 
37150 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65  after the update
37160 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a   takes place..**
37170 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68  .** The update h
37180 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ook is not invok
37190 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c  ed when internal
371a0 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61   system tables a
371b0 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28  re.** modified (
371c0 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74  i.e. sqlite_mast
371d0 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65  er and sqlite_se
371e0 71 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49  quence)..**.** I
371f0 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69  f another functi
37200 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c  on was previousl
37210 79 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74  y registered, it
37220 73 20 70 41 72 67 20 76 61 6c 75 65 0a 2a 2a 20  s pArg value.** 
37230 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
37240 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20  herwise NULL is 
37250 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
37260 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
37270 2a 20 7b 48 31 32 39 37 31 7d 20 54 68 65 20 5b  * {H12971} The [
37280 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
37290 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65  ook(D,F,P)] inte
372a0 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65  rface causes the
372b0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
372c0 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 46        function F
372d0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
372e0 69 74 68 20 66 69 72 73 74 20 70 61 72 61 6d 65  ith first parame
372f0 74 65 72 20 50 20 77 68 65 6e 65 76 65 72 0a 2a  ter P whenever.*
37300 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 61 62  *          a tab
37310 6c 65 20 72 6f 77 20 69 73 20 6d 6f 64 69 66 69  le row is modifi
37320 65 64 2c 20 69 6e 73 65 72 74 65 64 2c 20 6f 72  ed, inserted, or
37330 20 64 65 6c 65 74 65 64 20 6f 6e 0a 2a 2a 20 20   deleted on.**  
37340 20 20 20 20 20 20 20 20 74 68 65 20 5b 64 61 74          the [dat
37350 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37360 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ] D..**.** {H129
37370 37 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  73} The [sqlite3
37380 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46  _update_hook(D,F
37390 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,P)] interface r
373a0 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
373b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
373c0 50 20 66 6f 72 20 74 68 65 20 70 72 65 76 69 6f  P for the previo
373d0 75 73 20 63 61 6c 6c 20 6f 6e 20 74 68 65 20 73  us call on the s
373e0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
373f0 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a 20  nnection] D,.** 
37400 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c           or NULL
37410 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 63   for the first c
37420 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  all..**.** {H129
37430 37 35 7d 20 49 66 20 74 68 65 20 75 70 64 61 74  75} If the updat
37440 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20  e hook callback 
37450 46 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 75 70  F in [sqlite3_up
37460 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  date_hook(D,F,P)
37470 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  ].**          is
37480 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 6e   NULL then the n
37490 6f 20 75 70 64 61 74 65 20 63 61 6c 6c 62 61 63  o update callbac
374a0 6b 73 20 61 72 65 20 6d 61 64 65 2e 0a 2a 2a 0a  ks are made..**.
374b0 2a 2a 20 7b 48 31 32 39 37 37 7d 20 45 61 63 68  ** {H12977} Each
374c0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
374d0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
374e0 46 2c 50 29 5d 20 6f 76 65 72 72 69 64 65 73 20  F,P)] overrides 
374f0 70 72 69 6f 72 20 63 61 6c 6c 73 0a 2a 2a 20 20  prior calls.**  
37500 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 73          to the s
37510 61 6d 65 20 69 6e 74 65 72 66 61 63 65 20 6f 6e  ame interface on
37520 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
37530 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37540 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 37 39  D..**.** {H12979
37550 7d 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  } The update hoo
37560 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f  k callback is no
37570 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69  t invoked when i
37580 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 0a 2a  nternal system.*
37590 2a 20 20 20 20 20 20 20 20 20 20 74 61 62 6c 65  *          table
375a0 73 20 73 75 63 68 20 61 73 20 73 71 6c 69 74 65  s such as sqlite
375b0 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69  _master and sqli
375c0 74 65 5f 73 65 71 75 65 6e 63 65 20 61 72 65 20  te_sequence are 
375d0 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  modified..**.** 
375e0 7b 48 31 32 39 38 31 7d 20 54 68 65 20 73 65 63  {H12981} The sec
375f0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
37600 20 74 68 65 20 75 70 64 61 74 65 20 63 61 6c 6c   the update call
37610 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
37620 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
37630 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c  TE_INSERT], [SQL
37640 49 54 45 5f 44 45 4c 45 54 45 5d 20 6f 72 20 5b  ITE_DELETE] or [
37650 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 0a  SQLITE_UPDATE],.
37660 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 70 65  **          depe
37670 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65  nding on the ope
37680 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73  ration that caus
37690 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ed the callback 
376a0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a  to be invoked..*
376b0 2a 0a 2a 2a 20 7b 48 31 32 39 38 33 7d 20 54 68  *.** {H12983} Th
376c0 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
376d0 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  th arguments to 
376e0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  the callback con
376f0 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 0a 2a 2a  tain pointers.**
37700 20 20 20 20 20 20 20 20 20 20 74 6f 20 7a 65 72            to zer
37710 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
37720 2d 38 20 73 74 72 69 6e 67 73 20 77 68 69 63 68  -8 strings which
37730 20 61 72 65 20 74 68 65 20 6e 61 6d 65 73 20 6f   are the names o
37740 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
37750 20 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74    database and t
37760 61 62 6c 65 20 74 68 61 74 20 69 73 20 62 65 69  able that is bei
37770 6e 67 20 75 70 64 61 74 65 64 2e 0a 0a 2a 2a 20  ng updated...** 
37780 7b 48 31 32 39 38 35 7d 20 54 68 65 20 66 69 6e  {H12985} The fin
37790 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61  al callback para
377a0 6d 65 74 65 72 20 69 73 20 74 68 65 20 72 6f 77  meter is the row
377b0 69 64 20 6f 66 20 74 68 65 20 72 6f 77 20 61 66  id of the row af
377c0 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
377d0 74 68 65 20 63 68 61 6e 67 65 20 6f 63 63 75 72  the change occur
377e0 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  s..*/.void *sqli
377f0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
37800 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
37810 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69  void(*)(void *,i
37820 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  nt ,char const *
37830 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71  ,char const *,sq
37840 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20  lite3_int64),.  
37850 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  void*.);../*.** 
37860 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
37870 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72   Or Disable Shar
37880 65 64 20 50 61 67 65 72 20 43 61 63 68 65 20 7b  ed Pager Cache {
37890 48 31 30 33 33 30 7d 20 3c 53 33 30 39 30 30 3e  H10330} <S30900>
378a0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73  .** KEYWORDS: {s
378b0 68 61 72 65 64 20 63 61 63 68 65 7d 20 7b 73 68  hared cache} {sh
378c0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 7d  ared cache mode}
378d0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
378e0 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
378f0 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72  isables the shar
37900 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62  ing of the datab
37910 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64  ase cache.** and
37920 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72   schema data str
37930 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20  uctures between 
37940 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
37950 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f  tion | connectio
37960 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61  ns].** to the sa
37970 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53 68 61  me database. Sha
37980 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
37990 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  if the argument 
379a0 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64  is true.** and d
379b0 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  isabled if the a
379c0 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73 65  rgument is false
379d0 2e 0a 2a 2a 0a 2a 2a 20 43 61 63 68 65 20 73 68  ..**.** Cache sh
379e0 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64  aring is enabled
379f0 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f   and disabled fo
37a00 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63  r an entire proc
37a10 65 73 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 54 68  ess. {END}.** Th
37a20 69 73 20 69 73 20 61 20 63 68 61 6e 67 65 20 61  is is a change a
37a30 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
37a40 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72  ion 3.5.0. In pr
37a50 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ior versions of 
37a60 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69  SQLite,.** shari
37a70 6e 67 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f  ng was enabled o
37a80 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65  r disabled for e
37a90 61 63 68 20 74 68 72 65 61 64 20 73 65 70 61 72  ach thread separ
37aa0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ately..**.** The
37ab0 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d   cache sharing m
37ac0 6f 64 65 20 73 65 74 20 62 79 20 74 68 69 73 20  ode set by this 
37ad0 69 6e 74 65 72 66 61 63 65 20 65 66 66 65 63 74  interface effect
37ae0 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  s all subsequent
37af0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  .** calls to [sq
37b00 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
37b10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
37b20 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
37b30 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45  _open16()]..** E
37b40 78 69 73 74 69 6e 67 20 64 61 74 61 62 61 73 65  xisting database
37b50 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e   connections con
37b60 74 69 6e 75 65 20 75 73 65 20 74 68 65 20 73 68  tinue use the sh
37b70 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68  aring mode.** th
37b80 61 74 20 77 61 73 20 69 6e 20 65 66 66 65 63 74  at was in effect
37b90 20 61 74 20 74 68 65 20 74 69 6d 65 20 74 68 65   at the time the
37ba0 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 0a 2a  y were opened..*
37bb0 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62  *.** Virtual tab
37bc0 6c 65 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 73  les cannot be us
37bd0 65 64 20 77 69 74 68 20 61 20 73 68 61 72 65 64  ed with a shared
37be0 20 63 61 63 68 65 2e 20 20 57 68 65 6e 20 73 68   cache.  When sh
37bf0 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
37c00 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73   enabled, the [s
37c10 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
37c20 64 75 6c 65 28 29 5d 20 41 50 49 20 75 73 65 64  dule()] API used
37c30 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20   to register.** 
37c40 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 77  virtual tables w
37c50 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72  ill always retur
37c60 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a  n an error..**.*
37c70 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
37c80 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
37c90 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63  K] if shared cac
37ca0 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f  he was enabled o
37cb0 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75  r disabled.** su
37cc0 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20  ccessfully.  An 
37cd0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
37ce0 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69  returned otherwi
37cf0 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64  se..**.** Shared
37d00 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c   cache is disabl
37d10 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42  ed by default. B
37d20 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63 68  ut this might ch
37d30 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72  ange in.** futur
37d40 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
37d50 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69  Lite.  Applicati
37d60 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61 62  ons that care ab
37d70 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  out shared.** ca
37d80 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75  che setting shou
37d90 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69 63  ld set it explic
37da0 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  itly..**.** INVA
37db0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
37dc0 31 30 33 33 31 7d 20 41 20 73 75 63 63 65 73 73  10331} A success
37dd0 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
37de0 66 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  f [sqlite3_enabl
37df0 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 42  e_shared_cache(B
37e00 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  )].**          w
37e10 69 6c 6c 20 65 6e 61 62 6c 65 20 6f 72 20 64 69  ill enable or di
37e20 73 61 62 6c 65 20 73 68 61 72 65 64 20 63 61 63  sable shared cac
37e30 68 65 20 6d 6f 64 65 20 66 6f 72 20 61 6e 79 20  he mode for any 
37e40 73 75 62 73 65 71 75 65 6e 74 6c 79 0a 2a 2a 20  subsequently.** 
37e50 20 20 20 20 20 20 20 20 20 63 72 65 61 74 65 64           created
37e60 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37e70 63 74 69 6f 6e 5d 20 69 6e 20 74 68 65 20 73 61  ction] in the sa
37e80 6d 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 0a 2a  me process..**.*
37e90 2a 20 7b 48 31 30 33 33 36 7d 20 57 68 65 6e 20  * {H10336} When 
37ea0 73 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20  shared cache is 
37eb0 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71  enabled, the [sq
37ec0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
37ed0 75 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ule()].**       
37ee0 20 20 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c     interface wil
37ef0 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
37f00 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20  an error..**.** 
37f10 7b 48 31 30 33 33 37 7d 20 54 68 65 20 5b 73 71  {H10337} The [sq
37f20 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
37f30 72 65 64 5f 63 61 63 68 65 28 42 29 5d 20 69 6e  red_cache(B)] in
37f40 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
37f50 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
37f60 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65  ITE_OK] if share
37f70 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62  d cache was enab
37f80 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20  led or disabled 
37f90 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 0a 2a 2a  successfully..**
37fa0 0a 2a 2a 20 7b 48 31 30 33 33 39 7d 20 53 68 61  .** {H10339} Sha
37fb0 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73  red cache is dis
37fc0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
37fd0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
37fe0 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
37ff0 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  ache(int);../*.*
38000 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 65  * CAPI3REF: Atte
38010 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70  mpt To Free Heap
38020 20 4d 65 6d 6f 72 79 20 7b 48 31 37 33 34 30 7d   Memory {H17340}
38030 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20   <S30220>.**.** 
38040 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  The sqlite3_rele
38050 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74  ase_memory() int
38060 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
38070 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a  to free N bytes.
38080 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  ** of heap memor
38090 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e  y by deallocatin
380a0 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20  g non-essential 
380b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
380c0 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68  ns.** held by th
380d0 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61  e database libra
380e0 72 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72  ry. {END}  Memor
380f0 79 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20  y used to cache 
38100 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65  database.** page
38110 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72  s to improve per
38120 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65  formance is an e
38130 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73  xample of non-es
38140 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a  sential memory..
38150 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  ** sqlite3_relea
38160 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75  se_memory() retu
38170 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
38180 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79  f bytes actually
38190 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68   freed,.** which
381a0 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f   might be more o
381b0 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20  r less than the 
381c0 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64  amount requested
381d0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
381e0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 34  TS:.**.** {H1734
381f0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
38200 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 4e  release_memory(N
38210 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  )] interface att
38220 65 6d 70 74 73 20 74 6f 0a 2a 2a 20 20 20 20 20  empts to.**     
38230 20 20 20 20 20 66 72 65 65 20 4e 20 62 79 74 65       free N byte
38240 73 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79  s of heap memory
38250 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67   by deallocating
38260 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 0a 2a   non-essential.*
38270 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72  *          memor
38280 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 68 65  y allocations he
38290 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61  ld by the databa
382a0 73 65 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a  se library..**.*
382b0 2a 20 7b 48 31 36 33 34 32 7d 20 54 68 65 20 5b  * {H16342} The [
382c0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
382d0 6d 65 6d 6f 72 79 28 4e 29 5d 20 72 65 74 75 72  memory(N)] retur
382e0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a  ns the number.**
382f0 20 20 20 20 20 20 20 20 20 20 6f 66 20 62 79 74            of byt
38300 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65  es actually free
38310 64 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20 62  d, which might b
38320 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 0a 2a  e more or less.*
38330 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20  *          than 
38340 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65  the amount reque
38350 73 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sted..*/.int sql
38360 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
38370 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  ory(int);../*.**
38380 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73   CAPI3REF: Impos
38390 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61  e A Limit On Hea
383a0 70 20 53 69 7a 65 20 7b 48 31 37 33 35 30 7d 20  p Size {H17350} 
383b0 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30220>.**.** T
383c0 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  he sqlite3_soft_
383d0 68 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74  heap_limit() int
383e0 65 72 66 61 63 65 20 70 6c 61 63 65 73 20 61 20  erface places a 
383f0 22 73 6f 66 74 22 20 6c 69 6d 69 74 0a 2a 2a 20  "soft" limit.** 
38400 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  on the amount of
38410 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61   heap memory tha
38420 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74  t may be allocat
38430 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a  ed by SQLite..**
38440 20 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20   If an internal 
38450 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65  allocation is re
38460 71 75 65 73 74 65 64 20 74 68 61 74 20 77 6f 75  quested that wou
38470 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a  ld exceed the.**
38480 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
38490 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  , [sqlite3_relea
384a0 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20  se_memory()] is 
384b0 69 6e 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a  invoked one or.*
384c0 2a 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  * more times to 
384d0 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70 61  free up some spa
384e0 63 65 20 62 65 66 6f 72 65 20 74 68 65 20 61 6c  ce before the al
384f0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 70 65 72 66  location is perf
38500 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ormed..**.** The
38510 20 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64   limit is called
38520 20 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65   "soft", because
38530 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c   if [sqlite3_rel
38540 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a  ease_memory()].*
38550 2a 20 63 61 6e 6e 6f 74 20 66 72 65 65 20 73 75  * cannot free su
38560 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
38570 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65 20 6c  to prevent the l
38580 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e 67 20  imit from being 
38590 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65  exceeded,.** the
385a0 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63   memory is alloc
385b0 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e 64 20  ated anyway and 
385c0 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70 65 72  the current oper
385d0 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a  ation proceeds..
385e0 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65  **.** A negative
385f0 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66   or zero value f
38600 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20  or N means that 
38610 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74  there is no soft
38620 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a   heap limit and.
38630 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  ** [sqlite3_rele
38640 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69  ase_memory()] wi
38650 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ll only be calle
38660 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73  d when memory is
38670 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 54   exhausted..** T
38680 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
38690 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65   for the soft he
386a0 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f  ap limit is zero
386b0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
386c0 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f  akes a best effo
386d0 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20  rt to honor the 
386e0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e  soft heap limit.
386f0 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 73  .** But if the s
38700 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63  oft heap limit c
38710 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64  annot be honored
38720 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c  , execution will
38730 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74  .** continue wit
38740 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f  hout error or no
38750 74 69 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69  tification.  Thi
38760 73 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d  s is why the lim
38770 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20  it is.** called 
38780 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20  a "soft" limit. 
38790 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20   It is advisory 
387a0 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  only..**.** Prio
387b0 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
387c0 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20  ion 3.5.0, this 
387d0 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e  routine only con
387e0 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d  strained the mem
387f0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64  ory.** allocated
38800 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
38810 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74  ead - the same t
38820 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74  hread in which t
38830 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72  his routine.** r
38840 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20  uns.  Beginning 
38850 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73  with SQLite vers
38860 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73  ion 3.5.0, the s
38870 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
38880 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20  s.** applied to 
38890 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65  all threads. The
388a0 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
388b0 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65   for the soft he
388c0 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61  ap limit.** is a
388d0 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e  n upper bound on
388e0 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72   the total memor
388f0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
38900 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e