/ Hex Artifact Content
Login

Artifact e5b4ebee23ce11d673a86df22a430458111aaab1:


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 34 36 20 32 30 30 38 2f 30  n,v 1.346 2008/0
05f0: 36 2f 32 31 20 31 36 3a 34 37 3a 30 39 20 6d 69  6/21 16:47:09 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 46 31 30  ion Numbers {F10
0840: 30 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  010}.**.** The S
0850: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 61 6e  QLITE_VERSION an
0860: 64 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  d SQLITE_VERSION
0870: 5f 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 73  _NUMBER #defines
0880: 20 69 6e 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74   in.** the sqlit
0890: 65 33 2e 68 20 66 69 6c 65 20 73 70 65 63 69 66  e3.h file specif
08a0: 79 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6f 66  y the version of
08b0: 20 53 51 4c 69 74 65 20 77 69 74 68 20 77 68 69   SQLite with whi
08c0: 63 68 0a 2a 2a 20 74 68 61 74 20 68 65 61 64 65  ch.** that heade
08d0: 72 20 66 69 6c 65 20 69 73 20 61 73 73 6f 63 69  r file is associ
08e0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
08f0: 22 76 65 72 73 69 6f 6e 22 20 6f 66 20 53 51 4c  "version" of SQL
0900: 69 74 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  ite is a string 
0910: 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 58 2e 59  of the form "X.Y
0920: 2e 5a 22 2e 0a 2a 2a 20 54 68 65 20 70 68 72 61  .Z"..** The phra
0930: 73 65 20 22 61 6c 70 68 61 22 20 6f 72 20 22 62  se "alpha" or "b
0940: 65 74 61 22 20 6d 69 67 68 74 20 62 65 20 61 70  eta" might be ap
0950: 70 65 6e 64 65 64 20 61 66 74 65 72 20 74 68 65  pended after the
0960: 20 5a 2e 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c   Z..** The X val
0970: 75 65 20 69 73 20 6d 61 6a 6f 72 20 76 65 72 73  ue is major vers
0980: 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6c 77 61 79  ion number alway
0990: 73 20 33 20 69 6e 20 53 51 4c 69 74 65 33 2e 0a  s 3 in SQLite3..
09a0: 2a 2a 20 54 68 65 20 58 20 76 61 6c 75 65 20 6f  ** The X value o
09b0: 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65 6e  nly changes when
09c0: 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
09d0: 74 69 62 69 6c 69 74 79 20 69 73 0a 2a 2a 20 62  tibility is.** b
09e0: 72 6f 6b 65 6e 20 61 6e 64 20 77 65 20 69 6e 74  roken and we int
09f0: 65 6e 64 20 74 6f 20 6e 65 76 65 72 20 62 72 65  end to never bre
0a00: 61 6b 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ak backwards com
0a10: 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 54  patibility..** T
0a20: 68 65 20 59 20 76 61 6c 75 65 20 69 73 20 74 68  he Y value is th
0a30: 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20  e minor version 
0a40: 6e 75 6d 62 65 72 20 61 6e 64 20 6f 6e 6c 79 20  number and only 
0a50: 63 68 61 6e 67 65 73 20 77 68 65 6e 0a 2a 2a 20  changes when.** 
0a60: 74 68 65 72 65 20 61 72 65 20 6d 61 6a 6f 72 20  there are major 
0a70: 66 65 61 74 75 72 65 20 65 6e 68 61 6e 63 65 6d  feature enhancem
0a80: 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 66 6f  ents that are fo
0a90: 72 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 6c  rwards compatibl
0aa0: 65 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 62 61 63  e.** but not bac
0ab0: 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 6c  kwards compatibl
0ac0: 65 2e 0a 2a 2a 20 54 68 65 20 5a 20 76 61 6c 75  e..** The Z valu
0ad0: 65 20 69 73 20 74 68 65 20 72 65 6c 65 61 73 65  e is the release
0ae0: 20 6e 75 6d 62 65 72 20 61 6e 64 20 69 73 20 69   number and is i
0af0: 6e 63 72 65 6d 65 6e 74 65 64 20 77 69 74 68 0a  ncremented with.
0b00: 2a 2a 20 65 61 63 68 20 72 65 6c 65 61 73 65 20  ** each release 
0b10: 62 75 74 20 72 65 73 65 74 73 20 62 61 63 6b 20  but resets back 
0b20: 74 6f 20 30 20 77 68 65 6e 65 76 65 72 20 59 20  to 0 whenever Y 
0b30: 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 2e 0a  is incremented..
0b40: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
0b50: 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  [sqlite3_libvers
0b60: 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
0b70: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
0b80: 75 6d 62 65 72 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  umber()]..**.** 
0b90: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
0ba0: 2a 20 7b 46 31 30 30 31 31 7d 20 54 68 65 20 53  * {F10011} The S
0bb0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 23 64  QLITE_VERSION #d
0bc0: 65 66 69 6e 65 20 69 6e 20 74 68 65 20 73 71 6c  efine in the sql
0bd0: 69 74 65 33 2e 68 20 68 65 61 64 65 72 20 66 69  ite3.h header fi
0be0: 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  le.**          e
0bf0: 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74  valuates to a st
0c00: 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61  ring literal tha
0c10: 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65 20  t is the SQLite 
0c20: 76 65 72 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  version.**      
0c30: 20 20 20 20 77 69 74 68 20 77 68 69 63 68 20 74      with which t
0c40: 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 20 69  he header file i
0c50: 73 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a  s associated..**
0c60: 0a 2a 2a 20 7b 46 31 30 30 31 34 7d 20 54 68 65  .** {F10014} The
0c70: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
0c80: 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 20 72  NUMBER #define r
0c90: 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e  esolves to an in
0ca0: 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  teger.**        
0cb0: 20 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65    with the value
0cc0: 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a   (X*1000000 + Y*
0cd0: 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20  1000 + Z) where 
0ce0: 58 2c 20 59 2c 20 61 6e 64 20 5a 0a 2a 2a 20 20  X, Y, and Z.**  
0cf0: 20 20 20 20 20 20 20 20 61 72 65 20 74 68 65 20          are the 
0d00: 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 2c 20 6d  major version, m
0d10: 69 6e 6f 72 20 76 65 72 73 69 6f 6e 2c 20 61 6e  inor version, an
0d20: 64 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72  d release number
0d30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
0d40: 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20  ITE_VERSION     
0d50: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
0d60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
0d70: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 20 2d 2d  RSION_NUMBER  --
0d80: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d  VERSION-NUMBER--
0d90: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0da0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
0db0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0dc0: 72 73 20 7b 46 31 30 30 32 30 7d 0a 2a 2a 20 4b  rs {F10020}.** K
0dd0: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
0de0: 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54  _version.**.** T
0df0: 68 65 73 65 20 66 65 61 74 75 72 65 73 20 70 72  hese features pr
0e00: 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 69  ovide the same i
0e10: 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68  nformation as th
0e20: 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  e [SQLITE_VERSIO
0e30: 4e 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c 49 54  N].** and [SQLIT
0e40: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0e50: 5d 20 23 64 65 66 69 6e 65 73 20 69 6e 20 74 68  ] #defines in th
0e60: 65 20 68 65 61 64 65 72 2c 20 62 75 74 20 61 72  e header, but ar
0e70: 65 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  e associated.** 
0e80: 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79  with the library
0e90: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
0ea0: 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 43 61  header file.  Ca
0eb0: 75 74 69 6f 75 73 20 70 72 6f 67 72 61 6d 6d 65  utious programme
0ec0: 72 73 20 6d 69 67 68 74 0a 2a 2a 20 69 6e 63 6c  rs might.** incl
0ed0: 75 64 65 20 61 20 63 68 65 63 6b 20 69 6e 20 74  ude a check in t
0ee0: 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  heir application
0ef0: 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 0a   to verify that.
0f00: 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  ** sqlite3_libve
0f10: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 61  rsion_number() a
0f20: 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
0f30: 65 20 76 61 6c 75 65 0a 2a 2a 20 5b 53 51 4c 49  e value.** [SQLI
0f40: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0f50: 52 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  R]..**.** The sq
0f60: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f70: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
0f80: 72 6e 73 20 74 68 65 20 73 61 6d 65 20 69 6e 66  rns the same inf
0f90: 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 0a 2a  ormation as is.*
0fa0: 2a 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  * in the sqlite3
0fb0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
0fc0: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
0fd0: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f   function is pro
0fe0: 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 75 73 65  vided.** for use
0ff0: 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44   in DLLs since D
1000: 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79  LL users usually
1010: 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 64 69 72   do not have dir
1020: 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 74  ect access to st
1030: 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74  ring.** constant
1040: 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c  s within the DLL
1050: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1060: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 30 32  TS:.**.** {F1002
1070: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
1080: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
1090: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
10a0: 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
10b0: 20 20 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71     an integer eq
10c0: 75 61 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 56  ual to [SQLITE_V
10d0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a  ERSION_NUMBER]..
10e0: 2a 2a 0a 2a 2a 20 7b 46 31 30 30 32 32 7d 20 54  **.** {F10022} T
10f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73  he [sqlite3_vers
1100: 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  ion] string cons
1110: 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  tant contains.**
1120: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 74 65            the te
1130: 78 74 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  xt of the [SQLIT
1140: 45 5f 56 45 52 53 49 4f 4e 5d 20 73 74 72 69 6e  E_VERSION] strin
1150: 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 30 32 33  g..**.** {F10023
1160: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  } The [sqlite3_l
1170: 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 66 75 6e  ibversion()] fun
1180: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 0a 2a 2a  ction returns.**
1190: 20 20 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e            a poin
11a0: 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
11b0: 74 65 33 5f 76 65 72 73 69 6f 6e 5d 20 73 74 72  te3_version] str
11c0: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 0a 2a 2f  ing constant..*/
11d0: 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
11e0: 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65  onst char sqlite
11f0: 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e  3_version[];.con
1200: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1210: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64  _libversion(void
1220: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  );.int sqlite3_l
1230: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1240: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
1250: 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f  API3REF: Test To
1260: 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62 72   See If The Libr
1270: 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61 66  ary Is Threadsaf
1280: 65 20 7b 46 31 30 31 30 30 7d 0a 2a 2a 0a 2a 2a  e {F10100}.**.**
1290: 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63   SQLite can be c
12a0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20  ompiled with or 
12b0: 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e  without mutexes.
12c0: 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 53 51    When.** the SQ
12d0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
12e0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
12f0: 61 63 72 6f 20 69 73 20 74 72 75 65 2c 20 6d 75  acro is true, mu
1300: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
1310: 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20  bled and SQLite 
1320: 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  is threadsafe.  
1330: 57 68 65 6e 20 74 68 61 74 20 6d 61 63 72 6f 20  When that macro 
1340: 69 73 20 66 61 6c 73 65 2c 0a 2a 2a 20 74 68 65  is false,.** the
1350: 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69   mutexes are omi
1360: 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74  tted.  Without t
1370: 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69  he mutexes, it i
1380: 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f  s not safe.** to
1390: 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63   use SQLite conc
13a0: 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f  urrently from mo
13b0: 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65  re than one thre
13c0: 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69  ad..**.** Enabli
13d0: 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72  ng mutexes incur
13e0: 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70  s a measurable p
13f0: 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c  erformance penal
1400: 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65  ty..** So if spe
1410: 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20  ed is of utmost 
1420: 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d  importance, it m
1430: 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69  akes sense to di
1440: 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74  sable.** the mut
1450: 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d  exes.  But for m
1460: 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d  aximum safety, m
1470: 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65  utexes should be
1480: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65   enabled..** The
1490: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
14a0: 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73  r is for mutexes
14b0: 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a   to be enabled..
14c0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
14d0: 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
14e0: 20 62 79 20 61 20 70 72 6f 67 72 61 6d 20 74 6f   by a program to
14f0: 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20   make sure that 
1500: 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f  the.** version o
1510: 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74  f SQLite that it
1520: 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69   is linking agai
1530: 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  nst was compiled
1540: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73   with.** the des
1550: 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20  ired setting of 
1560: 74 68 65 20 53 51 4c 49 54 45 5f 54 48 52 45 41  the SQLITE_THREA
1570: 44 53 41 46 45 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  DSAFE macro..**.
1580: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1590: 2a 0a 2a 2a 20 7b 46 31 30 31 30 31 7d 20 54 68  *.** {F10101} Th
15a0: 65 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  e [sqlite3_threa
15b0: 64 73 61 66 65 28 29 5d 20 66 75 6e 63 74 69 6f  dsafe()] functio
15c0: 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 7a 65 72  n returns nonzer
15d0: 6f 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  o if.**         
15e0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
15f0: 69 6c 65 64 20 77 69 74 68 20 69 74 73 20 6d 75  iled with its mu
1600: 74 65 78 65 73 20 65 6e 61 62 6c 65 64 20 6f 72  texes enabled or
1610: 20 7a 65 72 6f 0a 2a 2a 20 20 20 20 20 20 20 20   zero.**        
1620: 20 20 69 66 20 53 51 4c 69 74 65 20 77 61 73 20    if SQLite was 
1630: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75  compiled with mu
1640: 74 65 78 65 73 20 64 69 73 61 62 6c 65 64 2e 0a  texes disabled..
1650: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
1660: 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b  hreadsafe(void);
1670: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1680: 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
1690: 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b 46 31  ction Handle {F1
16a0: 32 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  2000}.** KEYWORD
16b0: 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  S: {database con
16c0: 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61  nection} {databa
16d0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a  se connections}.
16e0: 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20  **.** Each open 
16f0: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
1700: 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  is represented b
1710: 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  y a pointer to a
1720: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a  n instance of.**
1730: 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75   the opaque stru
1740: 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c  cture named "sql
1750: 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73  ite3".  It is us
1760: 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66  eful to think of
1770: 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70   an sqlite3.** p
1780: 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a  ointer as an obj
1790: 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ect.  The [sqlit
17a0: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
17b0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
17c0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
17d0: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
17e0: 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f  faces are its co
17f0: 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20  nstructors, and 
1800: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
1810: 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64 65 73 74  ].** is its dest
1820: 72 75 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61  ructor.  There a
1830: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e  re many other in
1840: 74 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61  terfaces (such a
1850: 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  s.** [sqlite3_pr
1860: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
1870: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
1880: 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a  ction()], and.**
1890: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
18a0: 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d  imeout()] to nam
18b0: 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61  e but three) tha
18c0: 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e  t are methods on
18d0: 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f   an.** sqlite3 o
18e0: 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65  bject..*/.typede
18f0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
1900: 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a   sqlite3;../*.**
1910: 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69   CAPI3REF: 64-Bi
1920: 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 20  t Integer Types 
1930: 7b 46 31 30 32 30 30 7d 0a 2a 2a 20 4b 45 59 57  {F10200}.** KEYW
1940: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
1950: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
1960: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
1970: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
1980: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
1990: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
19a0: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
19b0: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
19c0: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
19d0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
19e0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
19f0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
1a00: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
1a10: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
1a20: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
1a30: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  type definitions
1a40: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f  ..** The sqlite_
1a50: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
1a60: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
1a70: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  e supported for 
1a80: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
1a90: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
1aa0: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1ab0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 30 31  S:.**.** {F10201
1ac0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f 69 6e  } The [sqlite_in
1ad0: 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  t64] and [sqlite
1ae0: 33 5f 69 6e 74 36 34 5d 20 74 79 70 65 73 20 73  3_int64] types s
1af0: 70 65 63 69 66 79 0a 2a 2a 20 20 20 20 20 20 20  pecify.**       
1b00: 20 20 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e     a 64-bit sign
1b10: 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  ed integer..**.*
1b20: 2a 20 7b 46 31 30 32 30 32 7d 20 54 68 65 20 5b  * {F10202} The [
1b30: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 5d 20 61  sqlite_uint64] a
1b40: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 75 69 6e 74  nd [sqlite3_uint
1b50: 36 34 5d 20 74 79 70 65 73 20 73 70 65 63 69 66  64] types specif
1b60: 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  y.**          a 
1b70: 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  64-bit unsigned 
1b80: 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 66 64  integer..*/.#ifd
1b90: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
1ba0: 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53  TYPE.  typedef S
1bb0: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
1bc0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
1bd0: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
1be0: 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  d SQLITE_INT64_T
1bf0: 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  YPE sqlite_uint6
1c00: 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  4;.#elif defined
1c10: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
1c20: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
1c30: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
1c40: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
1c50: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
1c60: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
1c70: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
1c80: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
1c90: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
1ca0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
1cb0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
1cc0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
1cd0: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
1ce0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
1cf0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
1d00: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
1d10: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
1d20: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
1d30: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
1d40: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
1d50: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
1d60: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
1d70: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
1d80: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
1d90: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23  ting-point..*/.#
1da0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
1db0: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
1dc0: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
1dd0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
1de0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
1df0: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
1e00: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
1e10: 74 69 6f 6e 20 7b 46 31 32 30 31 30 7d 0a 2a 2a  tion {F12010}.**
1e20: 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1e30: 20 69 73 20 74 68 65 20 64 65 73 74 72 75 63 74   is the destruct
1e40: 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  or for the [sqli
1e50: 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  te3] object..**.
1e60: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
1e70: 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f  should [sqlite3_
1e80: 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
1e90: 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72  ize] all [prepar
1ea0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a  ed statements].*
1eb0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  * and [sqlite3_b
1ec0: 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73  lob_close | clos
1ed0: 65 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  e] all [sqlite3_
1ee0: 62 6c 6f 62 20 7c 20 42 4c 4f 42 73 5d 20 61 73  blob | BLOBs] as
1ef0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
1f00: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
1f10: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
1f20: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
1f30: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 0a 2a  se the object..*
1f40: 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6e  * The [sqlite3_n
1f50: 65 78 74 5f 73 74 6d 74 28 29 5d 20 69 6e 74 65  ext_stmt()] inte
1f60: 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
1f70: 64 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 0a  d to locate all.
1f80: 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
1f90: 74 65 6d 65 6e 74 73 5d 20 61 73 73 6f 63 69 61  tements] associa
1fa0: 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61  ted with a [data
1fb0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1fc0: 20 69 66 20 64 65 73 69 72 65 64 2e 0a 2a 2a 20   if desired..** 
1fd0: 54 79 70 69 63 61 6c 20 63 6f 64 65 20 6d 69 67  Typical code mig
1fe0: 68 74 20 6c 6f 6f 6b 20 6c 69 6b 65 20 74 68 69  ht look like thi
1ff0: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
2000: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 73 71  uote><pre>.** sq
2010: 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2020: 74 3b 0a 2a 2a 20 77 68 69 6c 65 28 20 28 70 53  t;.** while( (pS
2030: 74 6d 74 20 3d 20 73 71 6c 69 74 65 33 5f 6e 65  tmt = sqlite3_ne
2040: 78 74 5f 73 74 6d 74 28 64 62 2c 20 30 29 29 21  xt_stmt(db, 0))!
2050: 3d 30 20 29 7b 0a 2a 2a 20 26 6e 62 73 70 3b 20  =0 ){.** &nbsp; 
2060: 20 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69    sqlite3_finali
2070: 7a 65 28 70 53 74 6d 74 29 3b 0a 2a 2a 20 7d 0a  ze(pStmt);.** }.
2080: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
2090: 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 49 66 20  quote>.**.** If 
20a0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
20b0: 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 69  ] is invoked whi
20c0: 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  le a transaction
20d0: 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65   is open,.** the
20e0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
20f0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
2100: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
2110: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2120: 2a 2a 20 7b 46 31 32 30 31 31 7d 20 54 68 65 20  ** {F12011} The 
2130: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
2140: 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65 73 74  ] interface dest
2150: 72 6f 79 73 20 61 6e 20 5b 73 71 6c 69 74 65 33  roys an [sqlite3
2160: 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20  ] object.**     
2170: 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 64 20 62       allocated b
2180: 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
2190: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
21a0: 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
21b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
21c0: 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
21d0: 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  open_v2()]..**.*
21e0: 2a 20 7b 46 31 32 30 31 32 7d 20 54 68 65 20 5b  * {F12012} The [
21f0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
2200: 20 66 75 6e 63 74 69 6f 6e 20 72 65 6c 65 61 73   function releas
2210: 65 73 20 61 6c 6c 20 6d 65 6d 6f 72 79 20 75 73  es all memory us
2220: 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
2230: 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e        connection
2240: 20 61 6e 64 20 63 6c 6f 73 65 73 20 61 6c 6c 20   and closes all 
2250: 6f 70 65 6e 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a  open files..**.*
2260: 2a 20 7b 46 31 32 30 31 33 7d 20 49 66 20 74 68  * {F12013} If th
2270: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2280: 63 74 69 6f 6e 20 63 6f 6e 74 61 69 6e 73 20 5b  ction contains [
2290: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22a0: 6e 74 73 5d 20 74 68 61 74 0a 2a 2a 20 20 20 20  nts] that.**    
22b0: 20 20 20 20 20 20 68 61 76 65 20 6e 6f 74 20 62        have not b
22c0: 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
22d0: 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
22e0: 64 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d],.**          
22f0: 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 63 6c  then [sqlite3_cl
2300: 6f 73 65 28 29 5d 20 72 65 74 75 72 6e 73 20 5b  ose()] returns [
2310: 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
2320: 20 6c 65 61 76 65 73 0a 2a 2a 20 20 20 20 20 20   leaves.**      
2330: 20 20 20 20 74 68 65 20 63 6f 6e 6e 65 63 74 69      the connecti
2340: 6f 6e 20 6f 70 65 6e 2e 0a 2a 2a 0a 2a 2a 20 7b  on open..**.** {
2350: 46 31 32 30 31 34 7d 20 50 61 73 73 69 6e 67 20  F12014} Passing 
2360: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2370: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
2380: 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
2390: 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31  op..**.** {F1201
23a0: 39 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  9} When [sqlite3
23b0: 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76  _close()] is inv
23c0: 6f 6b 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62  oked on a [datab
23d0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
23e0: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74  **          that
23f0: 20 68 61 73 20 61 20 70 65 6e 64 69 6e 67 20 74   has a pending t
2400: 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 20  ransaction, the 
2410: 74 72 61 6e 73 61 63 74 69 6f 6e 20 73 68 61 6c  transaction shal
2420: 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  l be.**         
2430: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
2440: 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a  .** LIMITATIONS:
2450: 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 30 31 35 7d 20  .**.** {U12015} 
2460: 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  The parameter to
2470: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
2480: 29 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 5b 73  )] must be an [s
2490: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 0a 2a  qlite3] object.*
24a0: 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
24b0: 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  er previously ob
24c0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
24d0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20  ite3_open()] or 
24e0: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
24f0: 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20 4e  equivalent, or N
2500: 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 30  ULL..**.** {U120
2510: 31 36 7d 20 54 68 65 20 70 61 72 61 6d 65 74 65  16} The paramete
2520: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  r to [sqlite3_cl
2530: 6f 73 65 28 29 5d 20 6d 75 73 74 20 6e 6f 74 20  ose()] must not 
2540: 68 61 76 65 20 62 65 65 6e 20 70 72 65 76 69 6f  have been previo
2550: 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  usly.**         
2560: 20 63 6c 6f 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20   closed..*/.int 
2570: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71  sqlite3_close(sq
2580: 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  lite3 *);../*.**
2590: 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20   The type for a 
25a0: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
25b0: 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65  n..** This is le
25c0: 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61  gacy and depreca
25d0: 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c  ted.  It is incl
25e0: 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69  uded for histori
25f0: 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  cal.** compatibi
2600: 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  lity and is not 
2610: 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74  documented..*/.t
2620: 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c  ypedef int (*sql
2630: 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76  ite3_callback)(v
2640: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
2650: 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a   char**);../*.**
2660: 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53   CAPI3REF: One-S
2670: 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74  tep Query Execut
2680: 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 20 7b 46  ion Interface {F
2690: 31 32 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12100}.**.** The
26a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
26b0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
26c0: 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79 20 6f 66  onvenient way of
26d0: 20 72 75 6e 6e 69 6e 67 20 6f 6e 65 20 6f 72 20   running one or 
26e0: 6d 6f 72 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74  more.** SQL stat
26f0: 65 6d 65 6e 74 73 20 77 69 74 68 6f 75 74 20 68  ements without h
2700: 61 76 69 6e 67 20 74 6f 20 77 72 69 74 65 20 61  aving to write a
2710: 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20   lot of C code. 
2720: 20 54 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   The UTF-8 encod
2730: 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ed.** SQL statem
2740: 65 6e 74 73 20 61 72 65 20 70 61 73 73 65 64 20  ents are passed 
2750: 69 6e 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  in as the second
2760: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2770: 6c 69 74 65 33 5f 65 78 65 63 28 29 2e 0a 2a 2a  lite3_exec()..**
2780: 20 54 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20   The statements 
2790: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 6f 6e  are evaluated on
27a0: 65 20 62 79 20 6f 6e 65 20 75 6e 74 69 6c 20 65  e by one until e
27b0: 69 74 68 65 72 20 61 6e 20 65 72 72 6f 72 20 6f  ither an error o
27c0: 72 0a 2a 2a 20 61 6e 20 69 6e 74 65 72 72 75 70  r.** an interrup
27d0: 74 20 69 73 20 65 6e 63 6f 75 6e 74 65 72 65 64  t is encountered
27e0: 2c 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 79 20  , or until they 
27f0: 61 72 65 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54  are all done.  T
2800: 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
2810: 0a 2a 2a 20 69 73 20 61 6e 20 6f 70 74 69 6f 6e  .** is an option
2820: 61 6c 20 63 61 6c 6c 62 61 63 6b 20 74 68 61 74  al callback that
2830: 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65   is invoked once
2840: 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66   for each row of
2850: 20 61 6e 79 20 71 75 65 72 79 0a 2a 2a 20 72 65   any query.** re
2860: 73 75 6c 74 73 20 70 72 6f 64 75 63 65 64 20 62  sults produced b
2870: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
2880: 65 6e 74 73 2e 20 20 54 68 65 20 35 74 68 20 70  ents.  The 5th p
2890: 61 72 61 6d 65 74 65 72 20 74 65 6c 6c 73 20 77  arameter tells w
28a0: 68 65 72 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65  here.** to write
28b0: 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61   any error messa
28c0: 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65  ges..**.** The e
28d0: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 70 61 73  rror message pas
28e0: 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68  sed back through
28f0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
2900: 65 72 20 69 73 20 68 65 6c 64 0a 2a 2a 20 69 6e  er is held.** in
2910: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
2920: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2930: 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f 20 61 76  alloc()].  To av
2940: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
2950: 6b 2c 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 69 6e  k,.** the callin
2960: 67 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  g application sh
2970: 6f 75 6c 64 20 63 61 6c 6c 20 5b 73 71 6c 69 74  ould call [sqlit
2980: 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 61 6e  e3_free()] on an
2990: 79 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  y error.** messa
29a0: 67 65 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  ge returned thro
29b0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
29c0: 6d 65 74 65 72 20 77 68 65 6e 20 69 74 20 68 61  meter when it ha
29d0: 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
29e0: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
29f0: 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ssage..**.** If 
2a00: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2a10: 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61 72  t in the 2nd par
2a20: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 6f  ameter is NULL o
2a30: 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
2a40: 67 0a 2a 2a 20 6f 72 20 61 20 73 74 72 69 6e 67  g.** or a string
2a50: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c 79   containing only
2a60: 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 20   whitespace and 
2a70: 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e  comments, then n
2a80: 6f 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  o SQL.** stateme
2a90: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
2aa0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
2ab0: 73 65 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  se is not change
2ac0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
2ad0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
2ae0: 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
2af0: 6e 74 65 64 20 69 6e 20 74 65 72 6d 73 20 6f 66  nted in terms of
2b00: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2b10: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
2b20: 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e  ite3_step()], an
2b30: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
2b40: 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  ize()]..** The s
2b50: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 72 6f  qlite3_exec() ro
2b60: 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 68 69  utine does nothi
2b70: 6e 67 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ng to the databa
2b80: 73 65 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  se that cannot b
2b90: 65 20 64 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 71  e done.** by [sq
2ba0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2bb0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
2bc0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
2bd0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
2be0: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
2bf0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30 31  S:.**.** {F12101
2c00: 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
2c10: 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
2c20: 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43  lite3_exec(D,S,C
2c30: 2c 41 2c 45 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,A,E)].**       
2c40: 20 20 20 73 68 61 6c 6c 20 65 76 61 6c 75 61 74     shall evaluat
2c50: 65 20 61 6c 6c 20 6f 66 20 74 68 65 20 55 54 46  e all of the UTF
2c60: 2d 38 20 65 6e 63 6f 64 65 64 2c 20 73 65 6d 69  -8 encoded, semi
2c70: 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 0a  colon-separated.
2c80: 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 20  **          SQL 
2c90: 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
2ca0: 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
2cb0: 64 20 73 74 72 69 6e 67 20 53 20 77 69 74 68 69  d string S withi
2cc0: 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
2cd0: 20 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65    context of the
2ce0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2cf0: 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
2d00: 7b 46 31 32 31 30 32 7d 20 49 66 20 74 68 65 20  {F12102} If the 
2d10: 53 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  S parameter to [
2d20: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53  sqlite3_exec(D,S
2d30: 2c 43 2c 41 2c 45 29 5d 20 69 73 20 4e 55 4c 4c  ,C,A,E)] is NULL
2d40: 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
2d50: 20 20 74 68 65 20 61 63 74 69 6f 6e 73 20 6f 66    the actions of
2d60: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 73   the interface s
2d70: 68 61 6c 6c 20 62 65 20 74 68 65 20 73 61 6d 65  hall be the same
2d80: 20 61 73 20 69 66 20 74 68 65 0a 2a 2a 20 20 20   as if the.**   
2d90: 20 20 20 20 20 20 20 53 20 70 61 72 61 6d 65 74         S paramet
2da0: 65 72 20 77 65 72 65 20 61 6e 20 65 6d 70 74 79  er were an empty
2db0: 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
2dc0: 46 31 32 31 30 34 7d 20 54 68 65 20 72 65 74 75  F12104} The retu
2dd0: 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  rn value of [sql
2de0: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61  ite3_exec()] sha
2df0: 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 4f 4b  ll be [SQLITE_OK
2e00: 5d 20 69 66 20 61 6c 6c 0a 2a 2a 20 20 20 20 20  ] if all.**     
2e10: 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65       SQL stateme
2e20: 6e 74 73 20 72 75 6e 20 73 75 63 63 65 73 73 66  nts run successf
2e30: 75 6c 6c 79 20 61 6e 64 20 74 6f 20 63 6f 6d 70  ully and to comp
2e40: 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46  letion..**.** {F
2e50: 31 32 31 30 35 7d 20 54 68 65 20 72 65 74 75 72  12105} The retur
2e60: 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  n value of [sqli
2e70: 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c  te3_exec()] shal
2e80: 6c 20 62 65 20 61 6e 20 61 70 70 72 6f 70 72 69  l be an appropri
2e90: 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ate.**          
2ea0: 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
2eb0: 63 6f 64 65 5d 20 69 66 20 61 6e 79 20 53 51 4c  code] if any SQL
2ec0: 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 73   statement fails
2ed0: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30 37 7d  ..**.** {F12107}
2ee0: 20 49 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   If one or more 
2ef0: 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  of the SQL state
2f00: 6d 65 6e 74 73 20 68 61 6e 64 65 64 20 74 6f 20  ments handed to 
2f10: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
2f20: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2f30: 75 72 6e 20 72 65 73 75 6c 74 73 20 61 6e 64 20  urn results and 
2f40: 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
2f50: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  r is not NULL, t
2f60: 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
2f70: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
2f80: 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20  ction specified 
2f90: 62 79 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  by the 3rd param
2fa0: 65 74 65 72 20 73 68 61 6c 6c 20 62 65 0a 2a 2a  eter shall be.**
2fb0: 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f 6b 65            invoke
2fc0: 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
2fd0: 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 0a 2a  row of result..*
2fe0: 2a 0a 2a 2a 20 7b 46 31 32 31 31 30 7d 20 49 66  *.** {F12110} If
2ff0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
3000: 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  turns a non-zero
3010: 20 76 61 6c 75 65 20 74 68 65 6e 20 5b 73 71 6c   value then [sql
3020: 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20  ite3_exec()].** 
3030: 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 61           shall a
3040: 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
3050: 74 65 6d 65 6e 74 20 69 74 20 69 73 20 63 75 72  tement it is cur
3060: 72 65 6e 74 6c 79 20 65 76 61 6c 75 61 74 69 6e  rently evaluatin
3070: 67 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  g,.**          s
3080: 6b 69 70 20 61 6c 6c 20 73 75 62 73 65 71 75 65  kip all subseque
3090: 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  nt SQL statement
30a0: 73 2c 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  s, and return [S
30b0: 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a  QLITE_ABORT]..**
30c0: 0a 2a 2a 20 7b 46 31 32 31 31 33 7d 20 54 68 65  .** {F12113} The
30d0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
30e0: 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20  ] routine shall 
30f0: 70 61 73 73 20 69 74 73 20 34 74 68 20 70 61 72  pass its 4th par
3100: 61 6d 65 74 65 72 20 74 68 72 6f 75 67 68 0a 2a  ameter through.*
3110: 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68  *          as th
3120: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
3130: 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  of the callback.
3140: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 31 36 7d 20  .**.** {F12116} 
3150: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  The [sqlite3_exe
3160: 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 65 74  c()] routine set
3170: 73 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  s the 2nd parame
3180: 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20  ter of its.**   
3190: 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20         callback 
31a0: 74 6f 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72  to be the number
31b0: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
31c0: 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
31d0: 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  f.**          re
31e0: 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  sult..**.** {F12
31f0: 31 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  119} The [sqlite
3200: 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e  3_exec()] routin
3210: 65 20 73 65 74 73 20 74 68 65 20 33 72 64 20 70  e sets the 3rd p
3220: 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a  arameter of its.
3230: 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
3240: 62 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72  back to be an ar
3250: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
3260: 74 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69  to strings holdi
3270: 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ng the.**       
3280: 20 20 20 76 61 6c 75 65 73 20 66 6f 72 20 65 61     values for ea
3290: 63 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  ch column in the
32a0: 20 63 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20   current result 
32b0: 73 65 74 20 72 6f 77 20 61 73 0a 2a 2a 20 20 20  set row as.**   
32c0: 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20         obtained 
32d0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
32e0: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
32f0: 0a 2a 2a 20 7b 46 31 32 31 32 32 7d 20 54 68 65  .** {F12122} The
3300: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3310: 5d 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 74  ] routine sets t
3320: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
3330: 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20   of its.**      
3340: 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20      callback to 
3350: 62 65 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  be an array of p
3360: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3370: 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a  gs holding the.*
3380: 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 73  *          names
3390: 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
33a0: 6e 73 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66  ns as obtained f
33b0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
33c0: 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a  umn_name()]..**.
33d0: 2a 2a 20 7b 46 31 32 31 32 35 7d 20 49 66 20 74  ** {F12125} If t
33e0: 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
33f0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
3400: 63 28 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65  c()] is NULL the
3410: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  n.**          [s
3420: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6e  qlite3_exec()] n
3430: 65 76 65 72 20 69 6e 76 6f 6b 65 73 20 61 20 63  ever invokes a c
3440: 61 6c 6c 62 61 63 6b 2e 20 20 41 6c 6c 20 71 75  allback.  All qu
3450: 65 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ery.**          
3460: 72 65 73 75 6c 74 73 20 61 72 65 20 73 69 6c 65  results are sile
3470: 6e 74 6c 79 20 64 69 73 63 61 72 64 65 64 2e 0a  ntly discarded..
3480: 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 31 7d 20 49  **.** {F12131} I
3490: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
34a0: 73 20 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20  s while parsing 
34b0: 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 61 6e  or evaluating an
34c0: 79 20 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20  y of the SQL.** 
34d0: 20 20 20 20 20 20 20 20 20 68 61 6e 64 65 64 20           handed 
34e0: 69 6e 20 74 68 65 20 53 20 70 61 72 61 6d 65 74  in the S paramet
34f0: 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65  er of [sqlite3_e
3500: 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20  xec(D,S,C,A,E)] 
3510: 61 6e 64 20 69 66 0a 2a 2a 20 20 20 20 20 20 20  and if.**       
3520: 20 20 20 74 68 65 20 45 20 70 61 72 61 6d 65 74     the E paramet
3530: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  er is not NULL, 
3540: 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78  then [sqlite3_ex
3550: 65 63 28 29 5d 20 73 68 61 6c 6c 20 73 74 6f 72  ec()] shall stor
3560: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  e.**          in
3570: 20 2a 45 20 61 6e 20 61 70 70 72 6f 70 72 69 61   *E an appropria
3580: 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  te error message
3590: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
35a0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  mory obtained.**
35b0: 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 5b            from [
35c0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
35d0: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 34  ]..**.** {F12134
35e0: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  } The [sqlite3_e
35f0: 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20  xec(D,S,C,A,E)] 
3600: 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65  routine shall se
3610: 74 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a  t the value of.*
3620: 2a 20 20 20 20 20 20 20 20 20 20 2a 45 20 74 6f  *          *E to
3630: 20 4e 55 4c 4c 20 69 66 20 45 20 69 73 20 6e 6f   NULL if E is no
3640: 74 20 4e 55 4c 4c 20 61 6e 64 20 74 68 65 72 65  t NULL and there
3650: 20 61 72 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a   are no errors..
3660: 2a 2a 0a 2a 2a 20 7b 46 31 32 31 33 37 7d 20 54  **.** {F12137} T
3670: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  he [sqlite3_exec
3680: 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 66 75 6e  (D,S,C,A,E)] fun
3690: 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74 20  ction shall set 
36a0: 74 68 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  the [error code]
36b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
36c0: 20 6d 65 73 73 61 67 65 20 61 63 63 65 73 73 69   message accessi
36d0: 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ble via [sqlite3
36e0: 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20  _errcode()],.** 
36f0: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
3700: 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64  3_errmsg()], and
3710: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
3720: 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  16()]..**.** {F1
3730: 32 31 33 38 7d 20 49 66 20 74 68 65 20 53 20 70  2138} If the S p
3740: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
3750: 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c  ite3_exec(D,S,C,
3760: 41 2c 45 29 5d 20 69 73 20 4e 55 4c 4c 20 6f 72  A,E)] is NULL or
3770: 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
3780: 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
3790: 63 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67  contains nothing
37a0: 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69 74   other than whit
37b0: 65 73 70 61 63 65 2c 20 63 6f 6d 6d 65 6e 74 73  espace, comments
37c0: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  ,.**          an
37d0: 64 2f 6f 72 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c  d/or semicolons,
37e0: 20 74 68 65 6e 20 72 65 73 75 6c 74 73 20 6f 66   then results of
37f0: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
3800: 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  e()],.**        
3810: 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73    [sqlite3_errms
3820: 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  g()], and [sqlit
3830: 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a  e3_errmsg16()].*
3840: 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c  *          shall
3850: 20 72 65 73 65 74 20 74 6f 20 69 6e 64 69 63 61   reset to indica
3860: 74 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a  te no errors..**
3870: 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a  .** LIMITATIONS:
3880: 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31 34 31 7d 20  .**.** {U12141} 
3890: 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
38a0: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
38b0: 65 78 65 63 28 29 5d 20 6d 75 73 74 20 62 65 20  exec()] must be 
38c0: 61 6e 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65  an valid and ope
38d0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  n.**          [d
38e0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38f0: 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 31  on]..**.** {U121
3900: 34 32 7d 20 54 68 65 20 64 61 74 61 62 61 73 65  42} The database
3910: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
3920: 20 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64 20 77   not be closed w
3930: 68 69 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  hile.**         
3940: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3950: 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ] is running..**
3960: 0a 2a 2a 20 7b 55 31 32 31 34 33 7d 20 54 68 65  .** {U12143} The
3970: 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
3980: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 5b 73 71  n should use [sq
3990: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 74 6f  lite3_free()] to
39a0: 20 66 72 65 65 0a 2a 2a 20 20 20 20 20 20 20 20   free.**        
39b0: 20 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61    the memory tha
39c0: 74 20 2a 65 72 72 6d 73 67 20 69 73 20 6c 65 66  t *errmsg is lef
39d0: 74 20 70 6f 69 6e 74 69 6e 67 20 61 74 20 6f 6e  t pointing at on
39e0: 63 65 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  ce the error.** 
39f0: 20 20 20 20 20 20 20 20 20 6d 65 73 73 61 67 65           message
3a00: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65   is no longer ne
3a10: 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32  eded..**.** {U12
3a20: 31 34 35 7d 20 54 68 65 20 53 51 4c 20 73 74 61  145} The SQL sta
3a30: 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 20 74  tement text in t
3a40: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
3a50: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
3a60: 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  c()].**         
3a70: 20 6d 75 73 74 20 72 65 6d 61 69 6e 20 75 6e 63   must remain unc
3a80: 68 61 6e 67 65 64 20 77 68 69 6c 65 20 5b 73 71  hanged while [sq
3a90: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73  lite3_exec()] is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74   running..*/.int
3ab0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20   sqlite3_exec(. 
3ac0: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20   sqlite3*,      
3ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ae0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
3af0: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
3b00: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
3b10: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20  *sql,           
3b20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b30: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
3b40: 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20  luated */.  int 
3b50: 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  (*callback)(void
3b60: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61  *,int,char**,cha
3b70: 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61  r**),  /* Callba
3b80: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  ck function */. 
3b90: 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20   void *,        
3ba0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bb0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31              /* 1
3bc0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  st argument to c
3bd0: 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61  allback */.  cha
3be0: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20  r **errmsg      
3bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c00: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
3c10: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
3c20: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
3c30: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
3c40: 43 6f 64 65 73 20 7b 46 31 30 32 31 30 7d 0a 2a  Codes {F10210}.*
3c50: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
3c60: 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64  TE_OK {error cod
3c70: 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d  e} {error codes}
3c80: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72  .** KEYWORDS: {r
3c90: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73  esult code} {res
3ca0: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a  ult codes}.**.**
3cb0: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
3cc0: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
3cd0: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
3ce0: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
3cf0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
3d00: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
3d10: 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f 72  cates success or
3d20: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
3d30: 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
3d40: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
3d50: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
3d60: 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  odes].*/.#define
3d70: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
3d80: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
3d90: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
3da0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
3db0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
3dc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
3dd0: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
3de0: 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20  /* SQL error or 
3df0: 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65  missing database
3e00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3e10: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
3e20: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
3e30: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
3e40: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
3e50: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
3e60: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
3e70: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
3e80: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
3e90: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
3ea0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
3eb0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
3ec0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
3ed0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3ee0: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
3ef0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
3f00: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
3f10: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3f20: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
3f30: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
3f40: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
3f50: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
3f60: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
3f70: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
3f80: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
3f90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3fa0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
3fb0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
3fc0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
3fd0: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
3fe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
3ff0: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4000: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4010: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4020: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4030: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4040: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4050: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4060: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
4070: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
4080: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
4090: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
40a0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
40b0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
40c0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
40d0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
40e0: 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45   12   /* NOT USE
40f0: 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63 6f  D. Table or reco
4100: 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a  rd not found */.
4110: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4120: 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20  ULL        13   
4130: 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69  /* Insertion fai
4140: 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61  led because data
4150: 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a  base is full */.
4160: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4170: 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20  ANTOPEN    14   
4180: 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65  /* Unable to ope
4190: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
41a0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
41b0: 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20  QLITE_PROTOCOL  
41c0: 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53    15   /* NOT US
41d0: 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f 63  ED. Database loc
41e0: 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72  k protocol error
41f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4200: 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31  TE_EMPTY       1
4210: 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
4220: 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66  is empty */.#def
4230: 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d  ine SQLITE_SCHEM
4240: 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54  A      17   /* T
4250: 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
4260: 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64  ma changed */.#d
4270: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f  efine SQLITE_TOO
4280: 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a  BIG      18   /*
4290: 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   String or BLOB 
42a0: 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d  exceeds size lim
42b0: 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  it */.#define SQ
42c0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
42d0: 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64   19   /* Abort d
42e0: 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74  ue to constraint
42f0: 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64   violation */.#d
4300: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4310: 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a  MATCH    20   /*
4320: 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61   Data type misma
4330: 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tch */.#define S
4340: 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20  QLITE_MISUSE    
4350: 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72    21   /* Librar
4360: 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74  y used incorrect
4370: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
4380: 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20  LITE_NOLFS      
4390: 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53   22   /* Uses OS
43a0: 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75   features not su
43b0: 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20  pported on host 
43c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
43d0: 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33  E_AUTH        23
43e0: 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74     /* Authorizat
43f0: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
4400: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52  efine SQLITE_FOR
4410: 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a  MAT      24   /*
4420: 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62   Auxiliary datab
4430: 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72  ase format error
4440: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4450: 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32  TE_RANGE       2
4460: 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d  5   /* 2nd param
4470: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
4480: 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67  bind out of rang
4490: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
44a0: 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20  ITE_NOTADB      
44b0: 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65  26   /* File ope
44c0: 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ned that is not 
44d0: 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
44e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
44f0: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30  E_ROW         10
4500: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  0  /* sqlite3_st
4510: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72  ep() has another
4520: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64   row ready */.#d
4530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e  efine SQLITE_DON
4540: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a  E        101  /*
4550: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4560: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
4570: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64  cuting */./* end
4580: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4590: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
45a0: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73  EF: Extended Res
45b0: 75 6c 74 20 43 6f 64 65 73 20 7b 46 31 30 32 32  ult Codes {F1022
45c0: 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0}.** KEYWORDS: 
45d0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
45e0: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20  code} {extended 
45f0: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
4600: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4610: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d  ded result code}
4620: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
4630: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49  t codes}.**.** I
4640: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f  n its default co
4650: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c  nfiguration, SQL
4660: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73  ite API routines
4670: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32   return one of 2
4680: 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  6 integer.** [SQ
4690: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
46a0: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
46b0: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
46c0: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
46d0: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
46e0: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
46f0: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
4700: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
4710: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
4720: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
4730: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
4740: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
4750: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
4760: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
4770: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
4780: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4790: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
47a0: 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e  .8 and later) in
47b0: 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74  clude.** support
47c0: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
47d0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61  result codes tha
47e0: 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64  t provide more d
47f0: 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74  etailed informat
4800: 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72  ion.** about err
4810: 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65  ors. The extende
4820: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
4830: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
4840: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
4850: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
4860: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
4870: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
4880: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
4890: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
48a0: 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74  .**.** Some of t
48b0: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74  he available ext
48c0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
48d0: 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65  es are listed he
48e0: 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65  re..** One may e
48f0: 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72  xpect the number
4900: 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73   of extended res
4910: 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62  ult codes will b
4920: 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72  e expand.** over
4930: 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65   time.  Software
4940: 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e   that uses exten
4950: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4960: 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a   should expect.*
4970: 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73  * to see new res
4980: 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74  ult codes in fut
4990: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
49a0: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
49b0: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75  e SQLITE_OK resu
49c0: 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76  lt code will nev
49d0: 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20  er be extended. 
49e0: 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a   It will always.
49f0: 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65  ** be exactly ze
4a00: 72 6f 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ro..**.** INVARI
4a10: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  ANTS:.**.** {F10
4a20: 32 32 33 7d 20 54 68 65 20 73 79 6d 62 6f 6c 69  223} The symboli
4a30: 63 20 6e 61 6d 65 20 66 6f 72 20 61 6e 20 65 78  c name for an ex
4a40: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4a50: 64 65 20 61 6c 77 61 79 73 20 63 6f 6e 74 61 69  de always contai
4a60: 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ns.**          a
4a70: 20 72 65 6c 61 74 65 64 20 70 72 69 6d 61 72 79   related primary
4a80: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 73 20   result code as 
4a90: 61 20 70 72 65 66 69 78 2e 0a 2a 2a 0a 2a 2a 20  a prefix..**.** 
4aa0: 7b 46 31 30 32 32 34 7d 20 50 72 69 6d 61 72 79  {F10224} Primary
4ab0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d   result code nam
4ac0: 65 73 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e  es contain a sin
4ad0: 67 6c 65 20 22 5f 22 20 63 68 61 72 61 63 74 65  gle "_" characte
4ae0: 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 35  r..**.** {F10225
4af0: 7d 20 45 78 74 65 6e 64 65 64 20 72 65 73 75 6c  } Extended resul
4b00: 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 63 6f 6e  t code names con
4b10: 74 61 69 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65  tain two or more
4b20: 20 22 5f 22 20 63 68 61 72 61 63 74 65 72 73 2e   "_" characters.
4b30: 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 36 7d 20  .**.** {F10226} 
4b40: 54 68 65 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  The numeric valu
4b50: 65 20 6f 66 20 61 6e 20 65 78 74 65 6e 64 65 64  e of an extended
4b60: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 63 6f 6e   result code con
4b70: 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  tains the.**    
4b80: 20 20 20 20 20 20 6e 75 6d 65 72 69 63 20 76 61        numeric va
4b90: 6c 75 65 20 6f 66 20 69 74 73 20 63 6f 72 72 65  lue of its corre
4ba0: 73 70 6f 6e 64 69 6e 67 20 70 72 69 6d 61 72 79  sponding primary
4bb0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 69 6e 0a   result code in.
4bc0: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 74 73 20  **          its 
4bd0: 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e  least significan
4be0: 74 20 38 20 62 69 74 73 2e 0a 2a 2f 0a 23 64 65  t 8 bits..*/.#de
4bf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4c00: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
4c10: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4c20: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
4c30: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4c40: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
4c50: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4c60: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
4c70: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4c80: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
4c90: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4ca0: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
4cb0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
4cc0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
4cd0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4ce0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
4cf0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4d00: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
4d10: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4d20: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
4d30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
4d40: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
4d50: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4d60: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
4d70: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
4d80: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
4d90: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
4da0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4db0: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
4dc0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
4dd0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
4de0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4df0: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
4e00: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4e10: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
4e20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e30: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
4e40: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4e50: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
4e60: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e70: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
4e80: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4e90: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
4ea0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4eb0: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
4ec0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4ed0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
4ee0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ef0: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
4f00: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f10: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
4f20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f30: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
4f40: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
4f50: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
4f60: 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  8))../*.** CAPI3
4f70: 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46  REF: Flags For F
4f80: 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69  ile Open Operati
4f90: 6f 6e 73 20 7b 46 31 30 32 33 30 7d 0a 2a 2a 0a  ons {F10230}.**.
4fa0: 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c  ** These bit val
4fb0: 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  ues are intended
4fc0: 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a   for use in the.
4fd0: 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ** 3rd parameter
4fe0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
4ff0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
5000: 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20  rface and.** in 
5010: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
5020: 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  r to the xOpen m
5030: 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20  ethod of the.** 
5040: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
5050: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
5060: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
5070: 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78  DONLY         0x
5080: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65  00000001.#define
5090: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
50a0: 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78  DWRITE        0x
50b0: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65  00000002.#define
50c0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
50d0: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78  ATE           0x
50e0: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
50f0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c   SQLITE_OPEN_DEL
5100: 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78  ETEONCLOSE    0x
5110: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
5120: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
5130: 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78  LUSIVE        0x
5140: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65  00000010.#define
5150: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
5160: 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  N_DB          0x
5170: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65  00000100.#define
5180: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
5190: 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  P_DB          0x
51a0: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
51b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41   SQLITE_OPEN_TRA
51c0: 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78  NSIENT_DB     0x
51d0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
51e0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
51f0: 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  N_JOURNAL     0x
5200: 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65  00000800.#define
5210: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
5220: 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  P_JOURNAL     0x
5230: 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65  00001000.#define
5240: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42   SQLITE_OPEN_SUB
5250: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78  JOURNAL       0x
5260: 30 30 30 30 32 30 30 30 0a 23 64 65 66 69 6e 65  00002000.#define
5270: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53   SQLITE_OPEN_MAS
5280: 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78  TER_JOURNAL   0x
5290: 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00004000../*.** 
52a0: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65  CAPI3REF: Device
52b0: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73   Characteristics
52c0: 20 7b 46 31 30 32 34 30 7d 0a 2a 2a 0a 2a 2a 20   {F10240}.**.** 
52d0: 54 68 65 20 78 44 65 76 69 63 65 43 61 70 61 62  The xDeviceCapab
52e0: 69 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 20 6f  ilities method o
52f0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
5300: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62  o_methods].** ob
5310: 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ject returns an 
5320: 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
5330: 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65   a vector of the
5340: 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61   these.** bit va
5350: 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20  lues expressing 
5360: 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74  I/O characterist
5370: 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20  ics of the mass 
5380: 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63  storage.** devic
5390: 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65  e that holds the
53a0: 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b   file that the [
53b0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
53c0: 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f  ds].** refers to
53d0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
53e0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
53f0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
5400: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
5410: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
5420: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
5430: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5440: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
5450: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
5460: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
5470: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
5480: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
5490: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
54a0: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
54b0: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
54c0: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
54d0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
54e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
54f0: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
5500: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
5510: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
5520: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
5530: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
5540: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
5550: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
5560: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
5570: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
5580: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
5590: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
55a0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
55b0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
55c0: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
55d0: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
55e0: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
55f0: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
5600: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
5610: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5620: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20  _IOCAP_ATOMIC   
5630: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5640: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
5650: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
5660: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5670: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
5680: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20  _IOCAP_ATOMIC1K 
5690: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
56a0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
56b0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20  _IOCAP_ATOMIC2K 
56c0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
56d0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
56e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20  _IOCAP_ATOMIC4K 
56f0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
5700: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5710: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20  _IOCAP_ATOMIC8K 
5720: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
5730: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5740: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
5750: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
5760: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5770: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
5780: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
5790: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
57a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
57b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
57c0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
57d0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
57e0: 4e 44 20 20 20 20 20 30 78 30 30 30 30 30 32 30  ND     0x0000020
57f0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5800: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
5810: 4c 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30  L      0x0000040
5820: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
5830: 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20  F: File Locking 
5840: 4c 65 76 65 6c 73 20 7b 46 31 30 32 35 30 7d 0a  Levels {F10250}.
5850: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5860: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5870: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5880: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5890: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
58a0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
58b0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
58c0: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
58d0: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
58e0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
58f0: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5900: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5910: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5920: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5930: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5940: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5950: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5960: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5970: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5980: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5990: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
59a0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
59b0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
59c0: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
59d0: 65 20 46 6c 61 67 73 20 7b 46 31 30 32 36 30 7d  e Flags {F10260}
59e0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
59f0: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
5a00: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
5a10: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
5a20: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
5a30: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
5a40: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
5a50: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
5a60: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
5a70: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
5a80: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
5a90: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
5aa0: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
5ab0: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
5ac0: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
5ad0: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
5ae0: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
5af0: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
5b00: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
5b10: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
5b20: 75 73 68 65 64 2e 20 54 68 65 20 53 51 4c 49 54  ushed. The SQLIT
5b30: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66 6c  E_SYNC_NORMAL fl
5b40: 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  ag means.** to u
5b50: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
5b60: 29 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 68 65  ) semantics. The
5b70: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
5b80: 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20  L flag means.** 
5b90: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 2d 58 20  to use Mac OS-X 
5ba0: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
5bb0: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
5bc0: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
5bd0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
5be0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
5bf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
5c00: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
5c10: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
5c20: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5c30: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
5c40: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
5c50: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
5c60: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
5c70: 6c 65 20 7b 46 31 31 31 31 30 7d 0a 2a 2a 0a 2a  le {F11110}.**.*
5c80: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
5c90: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
5ca0: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
5cb0: 6c 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20  le in the OS.** 
5cc0: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 2e  interface layer.
5cd0: 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20    Individual OS 
5ce0: 69 6e 74 65 72 66 61 63 65 20 69 6d 70 6c 65 6d  interface implem
5cf0: 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a  entations will.*
5d00: 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61  * want to subcla
5d10: 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62  ss this object b
5d20: 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69  y appending addi
5d30: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a  tional fields.**
5d40: 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75   for their own u
5d50: 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64  se.  The pMethod
5d60: 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69  s entry is a poi
5d70: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
5d80: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5d90: 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
5da0: 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66  efines methods f
5db0: 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a  or performing.**
5dc0: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
5dd0: 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  on the open file
5de0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
5df0: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
5e00: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73   sqlite3_file;.s
5e10: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
5e20: 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72  le {.  const str
5e30: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
5e40: 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73  ethods *pMethods
5e50: 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f  ;  /* Methods fo
5e60: 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a  r an open file *
5e70: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
5e80: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
5e90: 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20  ce File Virtual 
5ea0: 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b  Methods Object {
5eb0: 46 31 31 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 45 76  F11120}.**.** Ev
5ec0: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
5ed0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
5ee0: 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f  vfs] xOpen metho
5ef0: 64 20 63 6f 6e 74 61 69 6e 73 20 61 20 70 6f 69  d contains a poi
5f00: 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 69 6e  nter to.** an in
5f10: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
5f20: 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
5f30: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 0a  ect defines the.
5f40: 2a 2a 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  ** methods used 
5f50: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
5f60: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 67  us operations ag
5f70: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66  ainst the open f
5f80: 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ile..**.** The f
5f90: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
5fa0: 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e   xSync may be on
5fb0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e  e of [SQLITE_SYN
5fc0: 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20  C_NORMAL] or.** 
5fd0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c  [SQLITE_SYNC_FUL
5fe0: 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63  L].  The first c
5ff0: 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72  hoice is the nor
6000: 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20  mal fsync()..** 
6010: 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63  The second choic
6020: 65 20 69 73 20 61 20 4d 61 63 20 4f 53 2d 58 20  e is a Mac OS-X 
6030: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20  style fullsync. 
6040: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e   The [SQLITE_SYN
6050: 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66  C_DATAONLY].** f
6060: 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20  lag may be ORed 
6070: 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  in to indicate t
6080: 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74  hat only the dat
6090: 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a  a of the file.**
60a0: 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f   and not its ino
60b0: 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  de needs to be s
60c0: 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ynced..**.** The
60d0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
60e0: 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  to xLock() and x
60f0: 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65  Unlock() are one
6100: 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c   of.** <ul>.** <
6110: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6120: 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _NONE],.** <li> 
6130: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
6140: 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RED],.** <li> [S
6150: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
6160: 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  VED],.** <li> [S
6170: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6180: 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  NG], or.** <li> 
6190: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
61a0: 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LUSIVE]..** </ul
61b0: 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63  >.** xLock() inc
61c0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
61d0: 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65   xUnlock() decre
61e0: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a  ases the lock..*
61f0: 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65  * The xCheckRese
6200: 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f  rvedLock() metho
6210: 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  d checks whether
6220: 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
6230: 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74  nnection,.** eit
6240: 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63  her in this proc
6250: 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f  ess or in some o
6260: 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73  ther process, is
6270: 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52   holding a RESER
6280: 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c  VED,.** PENDING,
6290: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f   or EXCLUSIVE lo
62a0: 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20  ck on the file. 
62b0: 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65   It returns true
62c0: 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f  .** if such a lo
62d0: 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61  ck exists and fa
62e0: 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  lse otherwise..*
62f0: 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f  *.** The xFileCo
6300: 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69  ntrol() method i
6310: 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65  s a generic inte
6320: 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77  rface that allow
6330: 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20  s custom.** VFS 
6340: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
6350: 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74  to directly cont
6360: 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  rol an open file
6370: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
6380: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
6390: 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65  rol()] interface
63a0: 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f  .  The second "o
63b0: 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  p" argument is a
63c0: 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63  n.** integer opc
63d0: 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  ode.  The third 
63e0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65  argument is a ge
63f0: 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e  neric pointer in
6400: 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69  tended to.** poi
6410: 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72  nt to a structur
6420: 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61  e that may conta
6430: 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  in arguments or 
6440: 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74  space in which t
6450: 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72  o.** write retur
6460: 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e  n values.  Poten
6470: 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46  tial uses for xF
6480: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67  ileControl() mig
6490: 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  ht be.** functio
64a0: 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f  ns to enable blo
64b0: 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68  cking locks with
64c0: 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68   timeouts, to ch
64d0: 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b  ange the.** lock
64e0: 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f  ing strategy (fo
64f0: 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65  r example to use
6500: 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29   dot-file locks)
6510: 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20  , to inquire.** 
6520: 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73  about the status
6530: 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74   of a lock, or t
6540: 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f  o break stale lo
6550: 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65  cks.  The SQLite
6560: 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65  .** core reserve
6570: 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65  s all opcodes le
6580: 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20  ss than 100 for 
6590: 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20  its own use..** 
65a0: 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  A [SQLITE_FCNTL_
65b0: 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74  LOCKSTATE | list
65c0: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
65d0: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
65e0: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
65f0: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
6600: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
6610: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
6620: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
6630: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
6640: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
6650: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a  d conflicts..**.
6660: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
6670: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
6680: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
6690: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
66a0: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
66b0: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
66c0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
66d0: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
66e0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
66f0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
6700: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
6710: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
6720: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
6730: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
6740: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
6750: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
6760: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
6770: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
6780: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
6790: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
67a0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
67b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
67c0: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
67d0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
67e0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
67f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6800: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
6810: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6820: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
6830: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6840: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
6850: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6860: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
6870: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6880: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
6890: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
68a0: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
68b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
68c0: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
68d0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
68e0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
68f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6900: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
6910: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
6920: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6930: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
6940: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
6950: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
6960: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
6970: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6980: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
6990: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
69a0: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
69b0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
69c0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
69d0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
69e0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
69f0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
6a00: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
6a10: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
6a20: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6a30: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
6a40: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
6a50: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
6a60: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
6a70: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
6a80: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
6a90: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
6aa0: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
6ab0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
6ac0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
6ad0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
6ae0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6af0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
6b00: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
6b10: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
6b20: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
6b30: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
6b40: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
6b50: 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
6b60: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
6b70: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
6b80: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
6b90: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
6ba0: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
6bb0: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
6bc0: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
6bd0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
6be0: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
6bf0: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
6c00: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
6c10: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
6c20: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
6c30: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
6c40: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
6c50: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
6c60: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
6c70: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
6c80: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
6c90: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
6ca0: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
6cb0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
6cc0: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
6cd0: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
6ce0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
6cf0: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
6d00: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
6d10: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
6d20: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
6d30: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
6d40: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
6d50: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
6d60: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
6d70: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65  _file*, int *pRe
6d80: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
6d90: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
6da0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
6db0: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
6dc0: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
6dd0: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
6de0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
6df0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
6e00: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
6e10: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74  le*);.  /* Addit
6e20: 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61  ional methods ma
6e30: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
6e40: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f  ture releases */
6e50: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
6e60: 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69  REF: Standard Fi
6e70: 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64  le Control Opcod
6e80: 65 73 20 7b 46 31 31 33 31 30 7d 0a 2a 2a 0a 2a  es {F11310}.**.*
6e90: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
6ea0: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70  constants are op
6eb0: 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46  codes for the xF
6ec0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
6ed0: 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  d.** of the [sql
6ee0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6ef0: 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20   object and for 
6f00: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6f10: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20  e_control()].** 
6f20: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
6f30: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
6f40: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70  TL_LOCKSTATE] op
6f50: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
6f60: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
6f70: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
6f80: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
6f90: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72  rol method to wr
6fa0: 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20  ite the current 
6fb0: 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20  state of.** the 
6fc0: 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51  lock (one of [SQ
6fd0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
6fe0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
6ff0: 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ARED],.** [SQLIT
7000: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
7010: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  , [SQLITE_LOCK_P
7020: 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c  ENDING], or [SQL
7030: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
7040: 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20  VE]).** into an 
7050: 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65  integer that the
7060: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70   pArg argument p
7070: 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63  oints to. This c
7080: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
7090: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
70a0: 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65  ing and only nee
70b0: 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ds to be support
70c0: 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54  ed when SQLITE_T
70d0: 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65  EST.** is define
70e0: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d..*/.#define SQ
70f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
7100: 54 41 54 45 20 20 20 20 20 20 20 20 31 0a 0a 2f  TATE        1../
7110: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
7120: 75 74 65 78 20 48 61 6e 64 6c 65 20 7b 46 31 37  utex Handle {F17
7130: 31 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  110}.**.** The m
7140: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
7150: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
7160: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
7170: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
7180: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
7190: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
71a0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
71b0: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
71c0: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
71d0: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
71e0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
71f0: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
7200: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
7210: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
7220: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
7230: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
7240: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
7250: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
7260: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
7270: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
7280: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
7290: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
72a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
72b0: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
72c0: 74 20 7b 46 31 31 31 34 30 7d 0a 2a 2a 0a 2a 2a  t {F11140}.**.**
72d0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
72e0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
72f0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
7300: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
7310: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
7320: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
7330: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
7340: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
7350: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
7360: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
7370: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
7380: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
7390: 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  stem"..**.** The
73a0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
73b0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
73c0: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
73d0: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
73e0: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
73f0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
7400: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
7410: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
7420: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
7430: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
7440: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
7450: 6e 63 72 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  ncreased..**.** 
7460: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65  The szOsFile fie
7470: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  ld is the size o
7480: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64  f the subclassed
7490: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a   [sqlite3_file].
74a0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65  ** structure use
74b0: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20  d by this VFS.  
74c0: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68  mxPathname is th
74d0: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
74e0: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d   of.** a pathnam
74f0: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a  e in this VFS..*
7500: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20  *.** Registered 
7510: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
7520: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20  cts are kept on 
7530: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f  a linked list fo
7540: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70  rmed by.** the p
7550: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54  Next pointer.  T
7560: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
7570: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61  register()].** a
7580: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  nd [sqlite3_vfs_
7590: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e  unregister()] in
75a0: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20  terfaces manage 
75b0: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20  this list.** in 
75c0: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61  a thread-safe wa
75d0: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  y.  The [sqlite3
75e0: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74  _vfs_find()] int
75f0: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68  erface.** search
7600: 65 73 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a  es the list..**.
7610: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
7620: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
7630: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
7640: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
7650: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
7660: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
7670: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
7680: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
7690: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
76a0: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
76b0: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
76c0: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
76d0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
76e0: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
76f0: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
7700: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
7710: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
7720: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
7730: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
7740: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
7750: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
7760: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
7770: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
7780: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
7790: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
77a0: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
77b0: 2a 0a 2a 2a 20 7b 46 31 31 31 34 31 7d 20 53 51  *.** {F11141} SQ
77c0: 4c 69 74 65 20 77 69 6c 6c 20 67 75 61 72 61 6e  Lite will guaran
77d0: 74 65 65 20 74 68 61 74 20 74 68 65 20 7a 46 69  tee that the zFi
77e0: 6c 65 6e 61 6d 65 20 73 74 72 69 6e 67 20 70 61  lename string pa
77f0: 73 73 65 64 20 74 6f 0a 2a 2a 20 78 4f 70 65 6e  ssed to.** xOpen
7800: 28 29 20 69 73 20 61 20 66 75 6c 6c 20 70 61 74  () is a full pat
7810: 68 6e 61 6d 65 20 61 73 20 67 65 6e 65 72 61 74  hname as generat
7820: 65 64 20 62 79 20 78 46 75 6c 6c 50 61 74 68 6e  ed by xFullPathn
7830: 61 6d 65 28 29 20 61 6e 64 0a 2a 2a 20 74 68 61  ame() and.** tha
7840: 74 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  t the string wil
7850: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
7860: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
7870: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
7880: 6c 6c 65 64 2e 20 20 7b 45 4e 44 7d 20 53 6f 20  lled.  {END} So 
7890: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
78a0: 65 5d 20 63 61 6e 20 73 74 6f 72 65 20 61 20 70  e] can store a p
78b0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
78c0: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
78d0: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
78e0: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
78f0: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
7900: 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34 32 7d 20 54  **.** {F11142} T
7910: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
7920: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
7930: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
7940: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
7950: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
7960: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
7970: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
7980: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
7990: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
79a0: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
79b0: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
79c0: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
79d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
79e0: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
79f0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 7b 45  OPEN_CREATE]. {E
7a00: 4e 44 7d 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ND}.** If xOpen(
7a10: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
7a20: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
7a30: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
7a40: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
7a50: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
7a60: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
7a70: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
7a80: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
7a90: 2a 2a 20 7b 46 31 31 31 34 33 7d 20 53 51 4c 69  ** {F11143} SQLi
7aa0: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64  te will also add
7ab0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
7ac0: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
7ad0: 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61  he xOpen().** ca
7ae0: 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ll, depending on
7af0: 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e   the object bein
7b00: 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20  g opened:.**.** 
7b10: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  <ul>.** <li>  [S
7b20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
7b30: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
7b40: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
7b50: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
7b60: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
7b70: 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  MP_DB].** <li>  
7b80: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
7b90: 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  P_JOURNAL].** <l
7ba0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
7bb0: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a  _TRANSIENT_DB].*
7bc0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
7bd0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d  OPEN_SUBJOURNAL]
7be0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
7bf0: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
7c00: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 20  URNAL].** </ul> 
7c10: 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  {END}.**.** The 
7c20: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
7c30: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
7c40: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
7c50: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
7c60: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
7c70: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
7c80: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
7c90: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
7ca0: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
7cb0: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
7cc0: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
7cd0: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
7ce0: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
7cf0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
7d00: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
7d10: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
7d20: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
7d30: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
7d40: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
7d50: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
7d60: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
7d70: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
7d80: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
7d90: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
7da0: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
7db0: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
7dc0: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
7dd0: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
7de0: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
7df0: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
7e00: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
7e10: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
7e20: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
7e30: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
7e40: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
7e50: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
7e60: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
7e70: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
7e80: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7e90: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
7ea0: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
7eb0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
7ec0: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
7ed0: 0a 2a 2a 20 7b 46 31 31 31 34 35 7d 20 54 68 65  .** {F11145} The
7ee0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
7ef0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61  LETEONCLOSE] fla
7f00: 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65  g means the file
7f10: 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65   should be.** de
7f20: 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73  leted when it is
7f30: 20 63 6c 6f 73 65 64 2e 20 20 7b 46 31 31 31 34   closed.  {F1114
7f40: 36 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  6} The [SQLITE_O
7f50: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
7f60: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
7f70: 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61  t for TEMP  data
7f80: 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20  bases, journals 
7f90: 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e  and for subjourn
7fa0: 61 6c 73 2e 0a 2a 2a 20 7b 46 31 31 31 34 37 7d  als..** {F11147}
7fb0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
7fc0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61  N_EXCLUSIVE] fla
7fd0: 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65  g means the file
7fe0: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
7ff0: 64 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69  d.** for exclusi
8000: 76 65 20 61 63 63 65 73 73 2e 20 20 54 68 69 73  ve access.  This
8010: 20 66 6c 61 67 20 69 73 20 73 65 74 20 66 6f 72   flag is set for
8020: 20 61 6c 6c 20 66 69 6c 65 73 20 65 78 63 65 70   all files excep
8030: 74 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 61 69  t.** for the mai
8040: 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  n database file.
8050: 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31   {END}.**.** {F1
8060: 31 31 34 38 7d 20 41 74 20 6c 65 61 73 74 20 73  1148} At least s
8070: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
8080: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
8090: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
80a0: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
80b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
80c0: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
80d0: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
80e0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
80f0: 6e 2e 20 20 7b 45 4e 44 7d 20 20 54 68 65 20 78  n.  {END}  The x
8100: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73  Open method does
8110: 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20   not have to.** 
8120: 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72  allocate the str
8130: 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c  ucture; it shoul
8140: 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69  d just fill it i
8150: 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 34 39  n..**.** {F11149
8160: 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  } The flags argu
8170: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28  ment to xAccess(
8180: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45  ) may be [SQLITE
8190: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a  _ACCESS_EXISTS].
81a0: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74  ** to test for t
81b0: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20  he existence of 
81c0: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  a file, or [SQLI
81d0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
81e0: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20  ITE] to.** test 
81f0: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
8200: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  s readable and w
8210: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c  ritable, or [SQL
8220: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d  ITE_ACCESS_READ]
8230: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74  .** to test whet
8240: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74  her a file is at
8250: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e   least readable.
8260: 20 20 7b 45 4e 44 7d 20 54 68 65 20 66 69 6c 65    {END} The file
8270: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
8280: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ectory..**.** {F
8290: 31 31 31 35 30 7d 20 53 51 4c 69 74 65 20 77 69  11150} SQLite wi
82a0: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
82b0: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
82c0: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
82d0: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
82e0: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
82f0: 68 6e 61 6d 65 2e 20 7b 46 31 31 31 35 31 7d 20  hname. {F11151} 
8300: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
8310: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
8320: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
8330: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
8340: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
8350: 74 68 6f 64 73 2e 20 7b 45 4e 44 7d 20 49 66 20  thods. {END} If 
8360: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
8370: 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67  r.** is not larg
8380: 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54  e enough, [SQLIT
8390: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75  E_CANTOPEN] shou
83a0: 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
83b0: 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a  Since this is.**
83c0: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61   handled as a fa
83d0: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c  tal error by SQL
83e0: 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65  ite, vfs impleme
83f0: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
8400: 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70  endeavor.** to p
8410: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73  revent this by s
8420: 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d  etting mxPathnam
8430: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e  e to a sufficien
8440: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e  tly large value.
8450: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  .**.** The xRand
8460: 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70  omness(), xSleep
8470: 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74  (), and xCurrent
8480: 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63 65  Time() interface
8490: 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74 72  s.** are not str
84a0: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
84b0: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
84c0: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
84d0: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
84e0: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
84f0: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
8500: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
8510: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
8520: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
8530: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
8540: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
8550: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
8560: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
8570: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
8580: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
8590: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
85a0: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
85b0: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
85c0: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
85d0: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
85e0: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
85f0: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
8600: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
8610: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54  econds given.  T
8620: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
8630: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
8640: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
8650: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
8660: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
8670: 20 74 69 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   time..*/.typede
8680: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
8690: 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73  _vfs sqlite3_vfs
86a0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
86b0: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
86c0: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
86d0: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
86e0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f  ersion number */
86f0: 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b  .  int szOsFile;
8700: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
8710: 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65  ize of subclasse
8720: 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a  d sqlite3_file *
8730: 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61  /.  int mxPathna
8740: 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  me;          /* 
8750: 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74  Maximum file pat
8760: 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a  hname length */.
8770: 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70    sqlite3_vfs *p
8780: 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65  Next;      /* Ne
8790: 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46  xt registered VF
87a0: 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  S */.  const cha
87b0: 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20  r *zName;       
87c0: 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20  /* Name of this 
87d0: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
87e0: 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tem */.  void *p
87f0: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
8800: 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20    /* Pointer to 
8810: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63  application-spec
8820: 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69  ific data */.  i
8830: 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
8840: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
8850: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
8860: 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20  ite3_file*,.    
8870: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66             int f
8880: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46  lags, int *pOutF
8890: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
88a0: 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f  Delete)(sqlite3_
88b0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
88c0: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e   *zName, int syn
88d0: 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  cDir);.  int (*x
88e0: 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f  Access)(sqlite3_
88f0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
8900: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61   *zName, int fla
8910: 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  gs, int *pResOut
8920: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c  );.  int (*xFull
8930: 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65  Pathname)(sqlite
8940: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
8950: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e  ar *zName, int n
8960: 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  Out, char *zOut)
8970: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f  ;.  void *(*xDlO
8980: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
8990: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
89a0: 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69  Filename);.  voi
89b0: 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71  d (*xDlError)(sq
89c0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
89d0: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72  nByte, char *zEr
89e0: 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 2a 28  rMsg);.  void *(
89f0: 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33  *xDlSym)(sqlite3
8a00: 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e  _vfs*,void*, con
8a10: 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c  st char *zSymbol
8a20: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
8a30: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
8a40: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
8a50: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
8a60: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
8a70: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
8a80: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
8a90: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
8aa0: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
8ab0: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
8ac0: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
8ad0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
8ae0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
8af0: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
8b00: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
8b10: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65  char *);.  /* Ne
8b20: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
8b30: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75  appended in figu
8b40: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
8b50: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
8b60: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
8b70: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
8b80: 69 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d  is happens. */.}
8b90: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8ba0: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
8bb0: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
8bc0: 68 6f 64 20 7b 46 31 31 31 39 30 7d 0a 2a 2a 0a  hod {F11190}.**.
8bd0: 2a 2a 20 7b 46 31 31 31 39 31 7d 20 54 68 65 73  ** {F11191} Thes
8be0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
8bf0: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
8c00: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
8c10: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
8c20: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
8c30: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
8c40: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44  fs] object. {END
8c50: 7d 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  }  They determin
8c60: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
8c70: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
8c80: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
8c90: 20 69 73 0a 2a 2a 20 6c 6f 6f 6b 69 6e 67 20 66   is.** looking f
8ca0: 6f 72 2e 20 20 7b 46 31 31 31 39 32 7d 20 57 69  or.  {F11192} Wi
8cb0: 74 68 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  th [SQLITE_ACCES
8cc0: 53 5f 45 58 49 53 54 53 5d 2c 20 74 68 65 20 78  S_EXISTS], the x
8cd0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
8ce0: 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 74   simply checks t
8cf0: 6f 20 73 65 65 20 69 66 20 74 68 65 20 66 69 6c  o see if the fil
8d00: 65 20 65 78 69 73 74 73 2e 20 7b 46 31 31 31 39  e exists. {F1119
8d10: 33 7d 20 57 69 74 68 0a 2a 2a 20 53 51 4c 49 54  3} With.** SQLIT
8d20: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
8d30: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
8d40: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 74 6f  method checks to
8d50: 20 73 65 65 0a 2a 2a 20 69 66 20 74 68 65 20 66   see.** if the f
8d60: 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61 64  ile is both read
8d70: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
8d80: 65 2e 20 20 7b 46 31 31 31 39 34 7d 20 57 69 74  e.  {F11194} Wit
8d90: 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 41 43 43 45  h.** SQLITE_ACCE
8da0: 53 53 5f 52 45 41 44 20 74 68 65 20 78 41 63 63  SS_READ the xAcc
8db0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
8dc0: 65 63 6b 73 20 74 6f 20 73 65 65 20 69 66 20 74  ecks to see if t
8dd0: 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61  he file is reada
8de0: 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ble..*/.#define 
8df0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
8e00: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
8e10: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
8e20: 52 45 41 44 57 52 49 54 45 20 31 0a 23 64 65 66  READWRITE 1.#def
8e30: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
8e40: 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f  S_READ      2../
8e50: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
8e60: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
8e70: 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 46 31  Lite Library {F1
8e80: 30 31 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0130}.**.** The 
8e90: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
8ea0: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
8eb0: 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
8ec0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 70  SQLite library p
8ed0: 72 69 6f 72 20 74 6f 20 75 73 65 2e 20 20 54 68  rior to use.  Th
8ee0: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
8ef0: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
8f00: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
8f10: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
8f20: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
8f30: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
8f40: 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  ize()..**.** A c
8f50: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
8f60: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
8f70: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
8f80: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
8f90: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
8fa0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
8fb0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
8fc0: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
8fd0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
8fe0: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
8ff0: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
9000: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9010: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
9020: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
9030: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
9040: 68 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79  hutdown().  Only
9050: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
9060: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
9070: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
9080: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
9090: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
90a0: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
90b0: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 20  armless no-ops. 
90c0: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
90d0: 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
90e0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
90f0: 74 69 6e 65 20 6d 61 79 20 62 65 20 63 61 6c 6c  tine may be call
9100: 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ed multiple time
9110: 73 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 6f 6e  s.** without con
9120: 73 65 71 75 65 6e 63 65 2e 20 20 53 65 63 6f 6e  sequence.  Secon
9130: 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
9140: 20 65 76 61 6c 75 61 74 69 6f 6e 73 20 6f 66 0a   evaluations of.
9150: 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ** sqlite3_initi
9160: 61 6c 69 7a 65 28 29 20 61 72 65 20 6e 6f 2d 6f  alize() are no-o
9170: 70 73 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ps.  The sqlite3
9180: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
9190: 75 74 69 6e 65 0a 2a 2a 20 6f 6e 6c 79 20 77 6f  utine.** only wo
91a0: 72 6b 73 20 74 68 65 20 66 69 72 73 74 20 74 69  rks the first ti
91b0: 6d 65 20 69 74 20 69 73 20 63 61 6c 6c 65 64 20  me it is called 
91c0: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 2c 20 6f  for a process, o
91d0: 72 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 74  r the first.** t
91e0: 69 6d 65 20 69 74 20 69 73 20 63 61 6c 6c 65 64  ime it is called
91f0: 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73   after sqlite3_s
9200: 68 75 74 64 6f 77 6e 28 29 2e 20 20 49 6e 20 61  hutdown().  In a
9210: 6c 6c 20 6f 74 68 65 72 20 63 61 73 65 73 2c 0a  ll other cases,.
9220: 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ** sqlite3_initi
9230: 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 20  alize() returns 
9240: 53 51 4c 49 54 45 5f 4f 4b 20 77 69 74 68 6f 75  SQLITE_OK withou
9250: 74 20 64 6f 69 6e 67 20 61 6e 79 20 72 65 61 6c  t doing any real
9260: 20 77 6f 72 6b 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f   work..**.** Amo
9270: 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c  ng other things,
9280: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9290: 69 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f  ize() shall invo
92a0: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  ke.** sqlite3_os
92b0: 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61  _init().  Simila
92c0: 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 68 75  rly, sqlite3_shu
92d0: 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c  tdown().** shall
92e0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
92f0: 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20  os_end()..**.** 
9300: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
9310: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
9320: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
9330: 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  OK on success..*
9340: 2a 20 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65  * If for some re
9350: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
9360: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
9370: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
9380: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
9390: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
93a0: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
93b0: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
93c0: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
93d0: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
93e0: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
93f0: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
9400: 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a  SQLITE_OK..**.**
9410: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
9420: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
9430: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
9440: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
9450: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
9460: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
9470: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
9480: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
9490: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
94a0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
94b0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
94c0: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
94d0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
94e0: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
94f0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9500: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
9510: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
9520: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
9530: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
9540: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
9550: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
9560: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
9570: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
9580: 64 79 2e 20 20 48 6f 77 65 76 65 72 2c 20 69 66  dy.  However, if
9590: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
95a0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
95b0: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
95c0: 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  T.** compile-tim
95d0: 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74  e option, then t
95e0: 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c  he automatic cal
95f0: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ls to sqlite3_in
9600: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72  itialize().** ar
9610: 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68  e omitted and th
9620: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
9630: 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  st call sqlite3_
9640: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
9650: 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74  ectly.** prior t
9660: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
9670: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
9680: 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d  ce.  For maximum
9690: 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a   portability,.**
96a0: 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
96b0: 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
96c0: 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f  ions always invo
96d0: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
96e0: 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63  alize().** direc
96f0: 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69  tly prior to usi
9700: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
9710: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
9720: 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a  Future releases.
9730: 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ** of SQLite may
9740: 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20   require this.  
9750: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
9760: 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68  the behavior exh
9770: 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53  ibited.** when S
9780: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
9790: 64 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4f 4d  d with SQLITE_OM
97a0: 49 54 5f 41 55 54 4f 49 4e 49 54 20 6d 69 67 68  IT_AUTOINIT migh
97b0: 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
97c0: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
97d0: 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
97e0: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
97f0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
9800: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
9810: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
9820: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
9830: 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
9840: 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
9850: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
9860: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
9870: 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
9880: 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
9890: 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
98a0: 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
98b0: 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
98c0: 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
98d0: 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
98e0: 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
98f0: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
9900: 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
9910: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
9920: 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
9930: 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
9940: 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
9950: 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
9960: 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
9970: 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
9980: 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
9990: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
99a0: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
99b0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
99c0: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
99d0: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
99e0: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
99f0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
9a00: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
9a10: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
9a20: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
9a30: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9a40: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
9a50: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
9a60: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
9a70: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
9a80: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
9a90: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
9aa0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9ab0: 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
9ac0: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
9ad0: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
9ae0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
9af0: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
9b00: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
9b10: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
9b20: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
9b30: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
9b40: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
9b50: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
9b60: 65 64 20 66 6f 72 20 75 6e 69 78 2c 20 77 69 6e  ed for unix, win
9b70: 64 6f 77 73 2c 20 6f 72 20 6f 73 2f 32 2e 0a 2a  dows, or os/2..*
9b80: 2a 20 57 68 65 6e 20 62 75 69 6c 74 20 66 6f 72  * When built for
9b90: 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
9ba0: 20 28 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49   (using the SQLI
9bb0: 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 20 63 6f  TE_OS_OTHER=1 co
9bc0: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
9bd0: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
9be0: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
9bf0: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
9c00: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
9c10: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
9c20: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
9c30: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
9c40: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
9c50: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
9c60: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
9c70: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
9c80: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
9c90: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 53 51  * must return SQ
9ca0: 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75 63 63 65  LITE_OK on succe
9cb0: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
9cc0: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
9cd0: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
9ce0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69  */.int sqlite3_i
9cf0: 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
9d00: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75  .int sqlite3_shu
9d10: 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74  tdown(void);.int
9d20: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
9d30: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
9d40: 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
9d50: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
9d60: 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
9d70: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
9d80: 79 20 7b 46 31 30 31 34 35 7d 0a 2a 2a 0a 2a 2a  y {F10145}.**.**
9d90: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
9da0: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
9db0: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
9dc0: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
9dd0: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
9de0: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
9df0: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
9e00: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
9e10: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
9e20: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
9e30: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
9e40: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
9e50: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
9e60: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
9e70: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
9e80: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
9e90: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
9ea0: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
9eb0: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
9ec0: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
9ed0: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
9ee0: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ds..**.** The sq
9ef0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
9f00: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
9f10: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
9f20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
9f30: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
9f40: 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
9f50: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
9f60: 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
9f70: 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
9f80: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
9f90: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  () is running.  
9fa0: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c  Furthermore, sql
9fb0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a  ite3_config().**
9fc0: 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76   may only be inv
9fd0: 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69  oked prior to li
9fe0: 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61  brary initializa
9ff0: 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
a000: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a010: 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68  e()] or after sh
a020: 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74  utdown by [sqlit
a030: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
a040: 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
a050: 2c 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 63  , that sqlite3_c
a060: 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63  onfig() can be c
a070: 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66  alled as part of
a080: 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
a090: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70  tation of an app
a0a0: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
a0b0: 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69   [sqlite3_os_ini
a0c0: 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  t()]..**.** The 
a0d0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
a0e0: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
a0f0: 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  () is an integer
a100: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
a110: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
a120: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
a130: 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
a140: 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
a150: 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
a160: 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
a170: 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
a180: 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
a190: 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
a1a0: 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  on the [SQLITE_C
a1b0: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
a1c0: 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  AD | configurati
a1d0: 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  on option].** in
a1e0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
a1f0: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ent..**.** When 
a200: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
a210: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
a220: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
a230: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f  returns SQLITE_O
a240: 4b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 74  K..** If the opt
a250: 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f  ion is unknown o
a260: 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  r SQLite is unab
a270: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70  le to set the op
a280: 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69  tion.** then thi
a290: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
a2a0: 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  s a non-zero [er
a2b0: 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e  ror code]..*/.in
a2c0: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  t sqlite3_config
a2d0: 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  (int, ...);../*.
a2e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
a2f0: 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52  ory Allocation R
a300: 6f 75 74 69 6e 65 73 20 7b 46 31 30 31 35 35 7d  outines {F10155}
a310: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
a320: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
a330: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
a340: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
a350: 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f  SQLite.** and lo
a360: 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
a370: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
a380: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f  es..**.** This o
a390: 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e  bject is used in
a3a0: 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20   only one place 
a3b0: 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e  in the SQLite in
a3c0: 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f  terface..** A po
a3d0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
a3e0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
a3f0: 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ect is the argum
a400: 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ent to.** [sqlit
a410: 65 33 5f 63 6f 6e 66 69 67 5d 20 77 68 65 6e 20  e3_config] when 
a420: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
a430: 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
a440: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
a450: 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65 61 74  LLOC].  By creat
a460: 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
a470: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
a480: 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
a490: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
a4a0: 66 69 67 5d 20 64 75 72 69 6e 67 20 63 6f 6e 66  fig] during conf
a4b0: 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 0a 2a 2a  iguration, an.**
a4c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e   application can
a4d0: 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
a4e0: 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 20 61  rnative memory a
a4f0: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
a500: 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 51 4c 69 74  tem.** for SQLit
a510: 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c  e to use for all
a520: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
a530: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
a540: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
a550: 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
a560: 61 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  a built-in memor
a570: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
a580: 20 69 73 0a 2a 2a 20 70 65 72 66 65 63 74 6c 79   is.** perfectly
a590: 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
a5a0: 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
a5b0: 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
a5c0: 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
a5d0: 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
a5e0: 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
a5f0: 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
a600: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
a610: 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
a620: 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
a630: 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
a640: 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
a650: 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
a660: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
a670: 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
a680: 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
a690: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
a6a0: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
a6b0: 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
a6c0: 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
a6d0: 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
a6e0: 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
a6f0: 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
a700: 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
a710: 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
a720: 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
a730: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
a740: 6f 63 2c 20 78 46 72 65 65 2c 20 61 6e 64 20 78  oc, xFree, and x
a750: 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 73 20  Realloc methods 
a760: 73 68 6f 75 6c 64 20 77 6f 72 6b 20 6c 69 6b 65  should work like
a770: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
a780: 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 20 72 65  , free(), and re
a790: 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f 6e  alloc() function
a7a0: 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
a7b0: 61 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  ard library..**.
a7c0: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
a7d0: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
a7e0: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
a7f0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
a800: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
a810: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
a820: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
a830: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
a840: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
a850: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
a860: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
a870: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
a880: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
a890: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
a8a0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
a8b0: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
a8c0: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
a8d0: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
a8e0: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
a8f0: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
a900: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
a910: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
a920: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
a930: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
a940: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
a950: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
a960: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
a970: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
a980: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
a990: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
a9a0: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 0a   power of 2..**.
a9b0: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
a9c0: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
a9d0: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
a9e0: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
a9f0: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
aa00: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
aa10: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
aa20: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
aa30: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
aa40: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
aa50: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
aa60: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
aa70: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
aa80: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
aa90: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
aaa0: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
aab0: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
aac0: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
aad0: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
aae0: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
aaf0: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
ab00: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
ab10: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a 74 79  xShutdown..*/.ty
ab20: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
ab30: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
ab40: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
ab50: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
ab60: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
ab70: 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
ab80: 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
ab90: 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
aba0: 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
abb0: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
abc0: 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
abd0: 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
abe0: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
abf0: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
ac00: 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
ac10: 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
ac20: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
ac30: 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
ac40: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
ac50: 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
ac60: 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
ac70: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
ac80: 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
ac90: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
aca0: 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
acb0: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
acc0: 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
acd0: 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
ace0: 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
acf0: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
ad00: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
ad10: 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
ad20: 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
ad30: 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
ad40: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
ad50: 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
ad60: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
ad70: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
ad80: 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
ad90: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
ada0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
adb0: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
adc0: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 46 31  tion Options {F1
add0: 30 31 36 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0160}.**.** Thes
ade0: 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
adf0: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
ae00: 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
ae10: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
ae20: 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
ae30: 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
ae40: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
ae50: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ae60: 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
ae70: 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
ae80: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
ae90: 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
aea0: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
aeb0: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
aec0: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68  this option.  Th
aed0: 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c  is option disabl
aee0: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
aef0: 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
af00: 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
af10: 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
af20: 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
af30: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 3c   single thread.<
af40: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
af50: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
af60: 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
af70: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
af80: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
af90: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69  his option.  Thi
afa0: 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65  s option disable
afb0: 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e  s.** mutexing on
afc0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
afd0: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
afe0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
aff0: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20  objects..** The 
b000: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72  application is r
b010: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73  esponsible for s
b020: 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73  erializing acces
b030: 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73  s to.** [databas
b040: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
b050: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
b060: 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f  tements].  But o
b070: 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20  ther mutexes.** 
b080: 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74  are enabled so t
b090: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
b0a0: 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69  be safe to use i
b0b0: 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
b0c0: 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e  ed.** environmen
b0d0: 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
b0e0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
b0f0: 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
b100: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
b110: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
b120: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54   this option.  T
b130: 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
b140: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
b150: 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
b160: 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
b170: 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
b180: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
b190: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
b1a0: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
b1b0: 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
b1c0: 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
b1d0: 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
b1e0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
b1f0: 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52  th.** SQLITE_THR
b200: 45 41 44 53 41 46 45 3d 31 29 20 74 68 65 20 53  EADSAFE=1) the S
b210: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
b220: 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c  ll itself serial
b230: 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ize access.** to
b240: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
b250: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
b260: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
b270: 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a  ] so that the.**
b280: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
b290: 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20  free to use the 
b2a0: 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
b2b0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68  onnection] or th
b2c0: 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61  e.** same [prepa
b2d0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
b2e0: 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  n different thre
b2f0: 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
b300: 74 69 6d 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  time.</dd>.**.**
b310: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
b320: 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  IG_MALLOC</dt>.*
b330: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
b340: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
b350: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
b360: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
b370: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
b380: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
b390: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
b3a0: 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
b3b0: 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
b3c0: 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
b3d0: 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
b3e0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
b3f0: 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
b400: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65   place of.** the
b410: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
b420: 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  on routines buil
b430: 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f  t into SQLite.</
b440: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
b450: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
b460: 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
b470: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
b480: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
b490: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
b4a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
b4b0: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
b4c0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
b4d0: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
b4e0: 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  e.  The [sqlite3
b4f0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
b500: 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
b510: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
b520: 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
b530: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b540: 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54  n routines..** T
b550: 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
b560: 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
b570: 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
b580: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b590: 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
b5a0: 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
b5b0: 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
b5c0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
b5d0: 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
b5e0: 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
b5f0: 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f  , for example.</
b600: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
b610: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
b620: 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  TATUS</dt>.** <d
b630: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
b640: 6b 65 73 20 73 69 6e 67 6c 65 20 62 6f 6f 6c 65  kes single boole
b650: 61 6e 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  an argument whic
b660: 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  h enables or dis
b670: 61 62 6c 65 73 0a 2a 2a 20 74 68 65 20 63 6f 6c  ables.** the col
b680: 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72  lection of memor
b690: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
b6a0: 74 69 73 74 69 63 73 2e 20 20 57 68 65 6e 20 64  tistics.  When d
b6b0: 69 73 61 62 6c 65 64 2c 20 74 68 65 0a 2a 2a 20  isabled, the.** 
b6c0: 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
b6d0: 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
b6e0: 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
b6f0: 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
b700: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
b710: 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
b720: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
b730: 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
b740: 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
b750: 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
b760: 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  eap_limit()].** 
b770: 20 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 6d    <li> sqlite3_m
b780: 65 6d 6f 72 79 5f 73 74 61 74 75 73 28 29 0a 2a  emory_status().*
b790: 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64  *   </ul>.** </d
b7a0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
b7b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
b7c0: 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CH</dt>.** <dd>T
b7d0: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
b7e0: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
b7f0: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
b800: 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
b810: 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  for.** scratch m
b820: 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72  emory.  There ar
b830: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
b840: 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  s:  A pointer to
b850: 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65   the memory, the
b860: 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
b870: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
b880: 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75  (sz), and the nu
b890: 6d 62 65 72 20 6f 66 20 62 75 66 66 65 72 73 20  mber of buffers 
b8a0: 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20  (N).  The sz.** 
b8b0: 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
b8c0: 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31   a multiple of 1
b8d0: 36 2e 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20  6. The first.** 
b8e0: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
b8f0: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f  point to an allo
b900: 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61  cation of at lea
b910: 73 74 20 28 73 7a 2b 34 29 2a 4e 20 62 79 74 65  st (sz+4)*N byte
b920: 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
b930: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
b940: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  no more than one
b950: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
b960: 61 74 20 6f 6e 63 65 20 70 65 72 20 74 68 72 65  at once per thre
b970: 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75  ad, so.** N shou
b980: 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 68 65  ld be set to the
b990: 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75   expected maximu
b9a0: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65  m number of thre
b9b0: 61 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20  ads.  The sz.** 
b9c0: 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64  parameter should
b9d0: 20 62 65 20 36 20 74 69 6d 65 73 20 74 68 65 20   be 6 times the 
b9e0: 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
b9f0: 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
ba00: 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 61 74  e size..** Scrat
ba10: 63 68 20 62 75 66 66 65 72 73 20 61 72 65 20 75  ch buffers are u
ba20: 73 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  sed as part of t
ba30: 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65  he btree balance
ba40: 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49 66 0a   operation.  If.
ba50: 2a 2a 20 54 68 65 20 62 74 72 65 65 20 62 61 6c  ** The btree bal
ba60: 61 6e 63 65 72 20 6e 65 65 64 73 20 61 64 64 69  ancer needs addi
ba70: 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 62 65  tional memory be
ba80: 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
ba90: 76 69 64 65 64 20 62 79 0a 2a 2a 20 73 63 72 61  vided by.** scra
baa0: 74 63 68 20 62 75 66 66 65 72 73 20 6f 72 20 69  tch buffers or i
bab0: 66 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75 66  f no scratch buf
bac0: 66 65 72 20 73 70 61 63 65 20 69 73 20 73 70 65  fer space is spe
bad0: 63 69 66 69 65 64 2c 20 74 68 65 6e 20 53 51 4c  cified, then SQL
bae0: 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f 20 5b  ite.** goes to [
baf0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
bb00: 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  ] to obtain the 
bb10: 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65 64 73 2e  memory it needs.
bb20: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
bb30: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
bb40: 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
bb50: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
bb60: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
bb70: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
bb80: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
bb90: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20   use for.** the 
bba0: 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
bbb0: 63 68 65 2e 20 20 54 68 65 72 65 20 61 72 65 20  che.  There are 
bbc0: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
bbd0: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   A pointer to th
bbe0: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65  e.** memory, the
bbf0: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
bc00: 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20  ge buffer (sz), 
bc10: 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
bc20: 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20  f pages (N)..** 
bc30: 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
bc40: 6d 75 73 74 20 62 65 20 61 20 70 6f 77 65 72 20  must be a power 
bc50: 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
bc60: 31 32 20 61 6e 64 20 33 32 37 36 38 2e 20 20 54  12 and 32768.  T
bc70: 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
bc80: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e  ment should poin
bc90: 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69  t to an allocati
bca0: 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 28  on of at least (
bcb0: 73 7a 2b 34 29 2a 4e 20 62 79 74 65 73 20 6f 66  sz+4)*N bytes of
bcc0: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69   memory..** SQLi
bcd0: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
bce0: 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
bcf0: 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
bd00: 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
bd10: 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
bd20: 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
bd30: 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
bd40: 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
bd50: 2e 20 20 49 66 20 61 64 64 69 74 69 6f 6e 61 6c  .  If additional
bd60: 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d  .** page cache m
bd70: 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20  emory is needed 
bd80: 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
bd90: 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
bda0: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  option, then.** 
bdb0: 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
bdc0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
bdd0: 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69  ] for the additi
bde0: 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61  onal storage spa
bdf0: 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ce.</dd>.**.** <
be00: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
be10: 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _HEAP</dt>.** <d
be20: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70  d>This option sp
be30: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
be40: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
be50: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
be60: 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f  use.** for all o
be70: 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
be80: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
be90: 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f  needs beyond tho
bea0: 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66  se provided.** f
beb0: 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
bec0: 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e  NFIG_SCRATCH] an
bed0: 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d [SQLITE_CONFIG
bee0: 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
bef0: 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
bf00: 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f 69  arguments: A poi
bf10: 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f  nter to the memo
bf20: 72 79 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ry, the number o
bf30: 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
bf40: 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c  e memory buffer,
bf50: 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d   and the minimum
bf60: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
bf70: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 69 73 20  .  When.** this 
bf80: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
bf90: 74 69 6f 6e 20 69 73 20 75 73 65 64 2c 20 53 51  tion is used, SQ
bfa0: 4c 69 74 65 20 6e 65 76 65 72 20 63 61 6c 6c 73  Lite never calls
bfb0: 20 74 68 65 20 73 79 73 74 65 6d 0a 2a 2a 20 6d   the system.** m
bfc0: 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
bfd0: 74 61 74 69 6f 6e 20 62 75 74 20 69 6e 73 74 65  tation but inste
bfe0: 61 64 20 75 73 65 73 20 74 68 65 20 73 75 70 70  ad uses the supp
bff0: 6c 69 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  lied memory buff
c000: 65 72 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66 79  er.** to satisfy
c010: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 6d 61   all [sqlite3_ma
c020: 6c 6c 6f 63 28 29 5d 20 72 65 71 75 65 73 74 73  lloc()] requests
c030: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
c040: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
c050: 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
c060: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
c070: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
c080: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
c090: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
c0a0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
c0b0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
c0c0: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
c0d0: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
c0e0: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
c0f0: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
c100: 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
c110: 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
c120: 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d  n place.** the m
c130: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
c140: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
c150: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
c160: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
c170: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
c180: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
c190: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
c1a0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
c1b0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
c1c0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
c1d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
c1e0: 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
c1f0: 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  cture.  The.** [
c200: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
c210: 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
c220: 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
c230: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
c240: 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72   defined mutex r
c250: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73  outines..** This
c260: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
c270: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
c280: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
c290: 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
c2a0: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
c2b0: 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
c2c0: 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
c2d0: 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
c2e0: 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
c2f0: 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
c300: 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  xample.</dd>.**.
c310: 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
c320: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
c330: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20  G_SINGLETHREAD  
c340: 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  1  /* nil */.#de
c350: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
c360: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20  IG_MULTITHREAD  
c370: 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   2  /* nil */.#d
c380: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
c390: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20  FIG_SERIALIZED  
c3a0: 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    3  /* nil */.#
c3b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
c3c0: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  NFIG_MALLOC     
c3d0: 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
c3e0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
c3f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c400: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
c410: 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
c420: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
c430: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
c440: 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
c450: 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69         6  /* voi
c460: 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
c470: 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
c480: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
c490: 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
c4a0: 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
c4b0: 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
c4c0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
c4d0: 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
c4e0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
c4f0: 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
c500: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
c510: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
c520: 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
c530: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
c540: 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
c550: 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
c560: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
c570: 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
c580: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
c590: 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
c5a0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
c5b0: 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a  ethods* */../*.*
c5c0: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
c5d0: 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
c5e0: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
c5f0: 64 65 73 20 7b 46 31 32 32 30 30 7d 0a 2a 2a 0a  des {F12200}.**.
c600: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
c610: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
c620: 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
c630: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
c640: 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
c650: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
c660: 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
c670: 69 74 65 2e 20 54 68 65 20 65 78 74 65 6e 64 65  ite. The extende
c680: 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
c690: 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
c6a0: 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
c6b0: 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
c6c0: 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 72 61  bility considera
c6d0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  tions..**.** INV
c6e0: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
c6f0: 46 31 32 32 30 31 7d 20 45 61 63 68 20 6e 65 77  F12201} Each new
c700: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
c710: 63 74 69 6f 6e 5d 20 73 68 61 6c 6c 20 68 61 76  ction] shall hav
c720: 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  e the.**        
c730: 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75    [extended resu
c740: 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
c750: 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
c760: 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  fault..**.** {F1
c770: 32 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  2202} The [sqlit
c780: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
c790: 6c 74 5f 63 6f 64 65 73 28 44 2c 46 29 5d 20 69  lt_codes(D,F)] i
c7a0: 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 65  nterface shall e
c7b0: 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20  nable.**        
c7c0: 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75    [extended resu
c7d0: 6c 74 20 63 6f 64 65 73 5d 20 66 6f 72 20 74 68  lt codes] for th
c7e0: 65 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  e  [database con
c7f0: 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20  nection] D.**   
c800: 20 20 20 20 20 20 20 69 66 20 74 68 65 20 46 20         if the F 
c810: 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 72 75  parameter is tru
c820: 65 2c 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  e, or disable th
c830: 65 6d 20 69 66 20 46 20 69 73 20 66 61 6c 73 65  em if F is false
c840: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
c850: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
c860: 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
c870: 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
c880: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
c890: 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20  st Insert Rowid 
c8a0: 7b 46 31 32 32 32 30 7d 0a 2a 2a 0a 2a 2a 20 45  {F12220}.**.** E
c8b0: 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20  ach entry in an 
c8c0: 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73  SQLite table has
c8d0: 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74   a unique 64-bit
c8e0: 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67   signed.** integ
c8f0: 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68  er key called th
c900: 65 20 22 72 6f 77 69 64 22 2e 20 54 68 65 20 72  e "rowid". The r
c910: 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
c920: 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
c930: 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
c940: 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
c950: 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
c960: 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
c970: 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
c980: 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
c990: 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
c9a0: 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a  red columns. If.
c9b0: 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
c9c0: 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
c9d0: 65 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52  e INTEGER PRIMAR
c9e0: 59 20 4b 45 59 20 74 68 65 6e 20 74 68 61 74 20  Y KEY then that 
c9f0: 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f  column.** is ano
ca00: 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74  ther alias for t
ca10: 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  he rowid..**.** 
ca20: 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
ca30: 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64 20 6f  urns the rowid o
ca40: 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
ca50: 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  t.** successful 
ca60: 49 4e 53 45 52 54 20 69 6e 74 6f 20 74 68 65 20  INSERT into the 
ca70: 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68  database from th
ca80: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
ca90: 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  ection].** in th
caa0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
cab0: 2e 20 20 49 66 20 6e 6f 20 73 75 63 63 65 73 73  .  If no success
cac0: 66 75 6c 20 49 4e 53 45 52 54 73 0a 2a 2a 20 68  ful INSERTs.** h
cad0: 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
cae0: 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61  d on that databa
caf0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a  se connection, z
cb00: 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
cb10: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 49 4e 53  .**.** If an INS
cb20: 45 52 54 20 6f 63 63 75 72 73 20 77 69 74 68 69  ERT occurs withi
cb30: 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65  n a trigger, the
cb40: 6e 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74  n the rowid of t
cb50: 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72  he inserted.** r
cb60: 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62  ow is returned b
cb70: 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61  y this routine a
cb80: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
cb90: 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67  igger is running
cba0: 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68  ..** But once th
cbb0: 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e  e trigger termin
cbc0: 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20  ates, the value 
cbd0: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
cbe0: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65   routine.** reve
cbf0: 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20  rts to the last 
cc00: 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62  value inserted b
cc10: 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
cc20: 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41  r fired..**.** A
cc30: 6e 20 49 4e 53 45 52 54 20 74 68 61 74 20 66 61  n INSERT that fa
cc40: 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e  ils due to a con
cc50: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
cc60: 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75  n is not a.** su
cc70: 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20  ccessful INSERT 
cc80: 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
cc90: 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
cca0: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
ccb0: 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 75 73  * routine.  Thus
ccc0: 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
ccd0: 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
cce0: 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
ccf0: 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
cd00: 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
cd10: 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
cd20: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
cd30: 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
cd40: 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
cd50: 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
cd60: 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52    When INSERT OR
cd70: 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f   REPLACE.** enco
cd80: 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61  unters a constra
cd90: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69  int violation, i
cda0: 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e  t does not fail.
cdb0: 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20    The.** INSERT 
cdc0: 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
cdd0: 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65  pletion after de
cde0: 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74  leting rows that
cdf0: 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63   caused.** the c
ce00: 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65  onstraint proble
ce10: 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52  m so INSERT OR R
ce20: 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61  EPLACE will alwa
ce30: 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65  ys change.** the
ce40: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
ce50: 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
ce60: 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70  .**.** For the p
ce70: 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
ce80: 72 6f 75 74 69 6e 65 2c 20 61 6e 20 49 4e 53 45  routine, an INSE
ce90: 52 54 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  RT is considered
cea0: 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
ceb0: 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
cec0: 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
ced0: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
cee0: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
cef0: 2a 0a 2a 2a 20 7b 46 31 32 32 32 31 7d 20 54 68  *.** {F12221} Th
cf00: 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
cf10: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
cf20: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
cf30: 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 20 20   the rowid.**   
cf40: 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6d 6f         of the mo
cf50: 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73  st recent succes
cf60: 73 66 75 6c 20 49 4e 53 45 52 54 20 70 65 72 66  sful INSERT perf
cf70: 6f 72 6d 65 64 20 6f 6e 20 74 68 65 20 73 61 6d  ormed on the sam
cf80: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  e.**          [d
cf90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
cfa0: 6f 6e 5d 20 61 6e 64 20 77 69 74 68 69 6e 20 74  on] and within t
cfb0: 68 65 20 73 61 6d 65 20 6f 72 20 68 69 67 68 65  he same or highe
cfc0: 72 20 6c 65 76 65 6c 0a 2a 2a 20 20 20 20 20 20  r level.**      
cfd0: 20 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74      trigger cont
cfe0: 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20  ext, or zero if 
cff0: 74 68 65 72 65 20 68 61 76 65 20 62 65 65 6e 20  there have been 
d000: 6e 6f 20 71 75 61 6c 69 66 79 69 6e 67 20 69 6e  no qualifying in
d010: 73 65 72 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  serts..**.** {F1
d020: 32 32 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  2223} The [sqlit
d030: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
d040: 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e  owid()] function
d050: 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
d060: 20 20 20 20 20 20 20 20 20 73 61 6d 65 20 76 61           same va
d070: 6c 75 65 20 77 68 65 6e 20 63 61 6c 6c 65 64 20  lue when called 
d080: 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 72  from the same tr
d090: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 0a 2a 2a  igger context.**
d0a0: 20 20 20 20 20 20 20 20 20 20 69 6d 6d 65 64 69            immedi
d0b0: 61 74 65 6c 79 20 62 65 66 6f 72 65 20 61 6e 64  ately before and
d0c0: 20 61 66 74 65 72 20 61 20 52 4f 4c 4c 42 41 43   after a ROLLBAC
d0d0: 4b 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54  K..**.** LIMITAT
d0e0: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32  IONS:.**.** {U12
d0f0: 32 33 32 7d 20 49 66 20 61 20 73 65 70 61 72 61  232} If a separa
d100: 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72  te thread perfor
d110: 6d 73 20 61 20 6e 65 77 20 49 4e 53 45 52 54 20  ms a new INSERT 
d120: 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  on the same.**  
d130: 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65          database
d140: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
d150: 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
d160: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
d170: 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
d180: 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
d190: 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
d1a0: 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
d1b0: 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a 2a 20 20  sert rowid,.**  
d1c0: 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65          then the
d1d0: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
d1e0: 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
d1f0: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
d200: 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
d210: 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
d220: 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61  d might not equa
d230: 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64  l either the old
d240: 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 20   or the new.**  
d250: 20 20 20 20 20 20 20 20 6c 61 73 74 20 69 6e 73          last ins
d260: 65 72 74 20 72 6f 77 69 64 2e 0a 2a 2f 0a 73 71  ert rowid..*/.sq
d270: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
d280: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
d290: 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
d2a0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
d2b0: 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
d2c0: 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
d2d0: 69 65 64 20 7b 46 31 32 32 34 30 7d 0a 2a 2a 0a  ied {F12240}.**.
d2e0: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
d2f0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
d300: 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20  ber of database 
d310: 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63  rows that were c
d320: 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73  hanged.** or ins
d330: 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
d340: 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
d350: 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
d360: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
d370: 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
d380: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
d390: 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
d3a0: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
d3b0: 2a 2a 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20  ** Only changes 
d3c0: 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c  that are directl
d3d0: 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  y specified by t
d3e0: 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  he INSERT, UPDAT
d3f0: 45 2c 0a 2a 2a 20 6f 72 20 44 45 4c 45 54 45 20  E,.** or DELETE 
d400: 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f  statement are co
d410: 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72  unted.  Auxiliar
d420: 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
d430: 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20   by.** triggers 
d440: 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
d450: 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
d460: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
d470: 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  )] function.** t
d480: 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c  o find the total
d490: 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
d4a0: 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61  es including cha
d4b0: 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74  nges caused by t
d4c0: 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41  riggers..**.** A
d4d0: 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73   "row change" is
d4e0: 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73   a change to a s
d4f0: 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73  ingle row of a s
d500: 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63  ingle table.** c
d510: 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45  aused by an INSE
d520: 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55  RT, DELETE, or U
d530: 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e  PDATE statement.
d540: 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61    Rows that.** a
d550: 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69  re changed as si
d560: 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 52 45  de effects of RE
d570: 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74  PLACE constraint
d580: 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20   resolution,.** 
d590: 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20  rollback, ABORT 
d5a0: 70 72 6f 63 65 73 73 69 6e 67 2c 20 44 52 4f 50  processing, DROP
d5b0: 20 54 41 42 4c 45 2c 20 6f 72 20 62 79 20 61 6e   TABLE, or by an
d5c0: 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61  y other.** mecha
d5d0: 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75  nisms do not cou
d5e0: 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77  nt as direct row
d5f0: 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20   changes..**.** 
d600: 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65  A "trigger conte
d610: 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f  xt" is a scope o
d620: 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74  f execution that
d630: 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65   begins and.** e
d640: 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72  nds with the scr
d650: 69 70 74 20 6f 66 20 61 20 74 72 69 67 67 65 72  ipt of a trigger
d660: 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74  .  Most SQL stat
d670: 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76  ements are.** ev
d680: 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20  aluated outside 
d690: 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20  of any trigger. 
d6a0: 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f   This is the "to
d6b0: 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67  p level".** trig
d6c0: 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66  ger context.  If
d6d0: 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73   a trigger fires
d6e0: 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
d6f0: 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72  vel, a.** new tr
d700: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73  igger context is
d710: 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65   entered for the
d720: 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61   duration of tha
d730: 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72  t one.** trigger
d740: 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63  .  Subtriggers c
d750: 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74  reate subcontext
d760: 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61  s for their dura
d770: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c  tion..**.** Call
d780: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ing [sqlite3_exe
d790: 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
d7a0: 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69  _step()] recursi
d7b0: 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  vely does.** not
d7c0: 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72   create a new tr
d7d0: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
d7e0: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
d7f0: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
d800: 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20  umber of direct 
d810: 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74  row changes in t
d820: 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
d830: 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
d840: 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  , or DELETE stat
d850: 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
d860: 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72   same.** trigger
d870: 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
d880: 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65  Thus, when calle
d890: 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  d from the top l
d8a0: 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74  evel, this funct
d8b0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ion returns the.
d8c0: 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  ** number of cha
d8d0: 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
d8e0: 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
d8f0: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
d900: 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f  E.** that also o
d910: 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74  ccurred at the t
d920: 6f 70 20 6c 65 76 65 6c 2e 20 20 57 69 74 68 69  op level.  Withi
d930: 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20  n the body of a 
d940: 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20  trigger,.** the 
d950: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
d960: 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  ) interface can 
d970: 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e  be called to fin
d980: 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  d the number of.
d990: 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ** changes in th
d9a0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
d9b0: 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
d9c0: 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
d9d0: 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
d9e0: 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79   within the body
d9f0: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69   of the same tri
da00: 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  gger..** However
da10: 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74  , the number ret
da20: 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69  urned does not i
da30: 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a  nclude changes.*
da40: 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74  * caused by subt
da50: 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68  riggers since th
da60: 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20 6f  ose have their o
da70: 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  wn context..**.*
da80: 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65  * SQLite impleme
da90: 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20  nts the command 
daa0: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
dab0: 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 57 48  le" without a WH
dac0: 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79  ERE clause.** by
dad0: 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65   dropping and re
dae0: 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62  creating the tab
daf0: 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75  le.  (This is mu
db00: 63 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67  ch faster than g
db10: 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20  oing.** through 
db20: 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64  and deleting ind
db30: 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73  ividual elements
db40: 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e   from the table.
db50: 29 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  )  Because of th
db60: 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69  is.** optimizati
db70: 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e  on, the deletion
db80: 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f  s in "DELETE FRO
db90: 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74  M table" are not
dba0: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64   row changes and
dbb0: 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20  .** will not be 
dbc0: 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65 20 73  counted by the s
dbd0: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
dbe0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74   or [sqlite3_tot
dbf0: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a  al_changes()].**
dc00: 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61   functions, rega
dc10: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75  rdless of the nu
dc20: 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73  mber of elements
dc30: 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69   that were origi
dc40: 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20  nally.** in the 
dc50: 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61  table.  To get a
dc60: 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74  n accurate count
dc70: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
dc80: 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20  f rows deleted, 
dc90: 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46  use.** "DELETE F
dca0: 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20  ROM table WHERE 
dcb0: 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a  1" instead..**.*
dcc0: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
dcd0: 0a 2a 2a 20 7b 46 31 32 32 34 31 7d 20 54 68 65  .** {F12241} The
dce0: 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
dcf0: 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68  s()] function sh
dd00: 61 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 6e  all return the n
dd10: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20  umber of.**     
dd20: 20 20 20 20 20 72 6f 77 20 63 68 61 6e 67 65 73       row changes
dd30: 20 63 61 75 73 65 64 20 62 79 20 74 68 65 20 6d   caused by the m
dd40: 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
dd50: 54 2c 20 55 50 44 41 54 45 2c 0a 2a 2a 20 20 20  T, UPDATE,.**   
dd60: 20 20 20 20 20 20 20 6f 72 20 44 45 4c 45 54 45         or DELETE
dd70: 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68   statement on th
dd80: 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
dd90: 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 0a 2a  connection and.*
dda0: 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 69  *          withi
ddb0: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 20 68 69  n the same or hi
ddc0: 67 68 65 72 20 74 72 69 67 67 65 72 20 63 6f 6e  gher trigger con
ddd0: 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66  text, or zero if
dde0: 20 74 68 65 72 65 20 68 61 76 65 0a 2a 2a 20 20   there have.**  
ddf0: 20 20 20 20 20 20 20 20 6e 6f 74 20 62 65 65 6e          not been
de00: 20 61 6e 79 20 71 75 61 6c 69 66 79 69 6e 67 20   any qualifying 
de10: 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a  row changes..**.
de20: 2a 2a 20 7b 46 31 32 32 34 33 7d 20 53 74 61 74  ** {F12243} Stat
de30: 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 66 6f  ements of the fo
de40: 72 6d 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  rm "DELETE FROM 
de50: 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 74 68 20  tablename" with 
de60: 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 57  no.**          W
de70: 48 45 52 45 20 63 6c 61 75 73 65 20 73 68 61 6c  HERE clause shal
de80: 6c 20 63 61 75 73 65 20 73 75 62 73 65 71 75 65  l cause subseque
de90: 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20  nt calls to.**  
dea0: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
deb0: 5f 63 68 61 6e 67 65 73 28 29 5d 20 74 6f 20 72  _changes()] to r
dec0: 65 74 75 72 6e 20 7a 65 72 6f 2c 20 72 65 67 61  eturn zero, rega
ded0: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 0a 2a 2a  rdless of the.**
dee0: 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
def0: 20 6f 66 20 72 6f 77 73 20 6f 72 69 67 69 6e 61   of rows origina
df00: 6c 6c 79 20 69 6e 20 74 68 65 20 74 61 62 6c 65  lly in the table
df10: 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49  ..**.** LIMITATI
df20: 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32  ONS:.**.** {U122
df30: 35 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 74  52} If a separat
df40: 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
df50: 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
df60: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
df70: 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ection.**       
df80: 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65     while [sqlite
df90: 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  3_changes()] is 
dfa0: 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
dfb0: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
dfc0: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 75  **          is u
dfd0: 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
dfe0: 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
dff0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
e000: 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
e010: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
e020: 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72  EF: Total Number
e030: 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
e040: 64 20 7b 46 31 32 32 36 30 7d 0a 2a 2a 0a 2a 2a  d {F12260}.**.**
e050: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   This function r
e060: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
e070: 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73  r of row changes
e080: 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 45 52   caused by INSER
e090: 54 2c 0a 2a 2a 20 55 50 44 41 54 45 20 6f 72 20  T,.** UPDATE or 
e0a0: 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
e0b0: 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74  s since the [dat
e0c0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e0d0: 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a  ] was opened..**
e0e0: 20 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75   The count inclu
e0f0: 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 20  des all changes 
e100: 66 72 6f 6d 20 61 6c 6c 20 74 72 69 67 67 65 72  from all trigger
e110: 20 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f 77 65   contexts.  Howe
e120: 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e  ver,.** the coun
e130: 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
e140: 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20  de changes used 
e150: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 52 45 50  to implement REP
e160: 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 73  LACE constraints
e170: 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b  ,.** do rollback
e180: 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65  s or ABORT proce
e190: 73 73 69 6e 67 2c 20 6f 72 20 44 52 4f 50 20 74  ssing, or DROP t
e1a0: 61 62 6c 65 20 70 72 6f 63 65 73 73 69 6e 67 2e  able processing.
e1b0: 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67 65 73 20  .** The changes 
e1c0: 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73  are counted as s
e1d0: 6f 6f 6e 20 61 73 20 74 68 65 20 73 74 61 74 65  oon as the state
e1e0: 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20  ment that makes 
e1f0: 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c  them is.** compl
e200: 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73  eted (when the s
e210: 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
e220: 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  is passed to [sq
e230: 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
e240: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
e250: 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a  nalize()])..**.*
e260: 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65  * SQLite impleme
e270: 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20  nts the command 
e280: 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
e290: 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 57 48  le" without a WH
e2a0: 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79  ERE clause.** by
e2b0: 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65   dropping and re
e2c0: 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62  creating the tab
e2d0: 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75  le.  (This is mu
e2e0: 63 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67  ch faster than g
e2f0: 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20  oing.** through 
e300: 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64  and deleting ind
e310: 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73  ividual elements
e320: 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e   from the table.
e330: 29 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  )  Because of th
e340: 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69  is.** optimizati
e350: 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e  on, the deletion
e360: 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f  s in "DELETE FRO
e370: 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74  M table" are not
e380: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64   row changes and
e390: 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20  .** will not be 
e3a0: 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65 20 73  counted by the s
e3b0: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
e3c0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74   or [sqlite3_tot
e3d0: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a  al_changes()].**
e3e0: 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61   functions, rega
e3f0: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75  rdless of the nu
e400: 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73  mber of elements
e410: 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69   that were origi
e420: 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20  nally.** in the 
e430: 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61  table.  To get a
e440: 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74  n accurate count
e450: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
e460: 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20  f rows deleted, 
e470: 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46  use.** "DELETE F
e480: 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20  ROM table WHERE 
e490: 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a  1" instead..**.*
e4a0: 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
e4b0: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
e4c0: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
e4d0: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
e4e0: 2a 2a 0a 2a 2a 20 7b 46 31 32 32 36 31 7d 20 54  **.** {F12261} T
e4f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
e500: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 72 65 74  l_changes()] ret
e510: 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e  urns the total n
e520: 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  umber.**        
e530: 20 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73    of row changes
e540: 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 45 52   caused by INSER
e550: 54 2c 20 55 50 44 41 54 45 2c 20 61 6e 64 2f 6f  T, UPDATE, and/o
e560: 72 20 44 45 4c 45 54 45 0a 2a 2a 20 20 20 20 20  r DELETE.**     
e570: 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 73 20       statements 
e580: 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
e590: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e5a0: 5d 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20 20 20 20  ], in any.**    
e5b0: 20 20 20 20 20 20 74 72 69 67 67 65 72 20 63 6f        trigger co
e5c0: 6e 74 65 78 74 2c 20 73 69 6e 63 65 20 74 68 65  ntext, since the
e5d0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
e5e0: 74 69 6f 6e 20 77 61 73 20 63 72 65 61 74 65 64  tion was created
e5f0: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 36 33 7d  ..**.** {F12263}
e600: 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 74   Statements of t
e610: 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45 20  he form "DELETE 
e620: 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20  FROM tablename" 
e630: 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20  with no.**      
e640: 20 20 20 20 57 48 45 52 45 20 63 6c 61 75 73 65      WHERE clause
e650: 20 73 68 61 6c 6c 20 6e 6f 74 20 63 68 61 6e 67   shall not chang
e660: 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
e670: 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rned.**         
e680: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74   by [sqlite3_tot
e690: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 2e 0a 2a  al_changes()]..*
e6a0: 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53  *.** LIMITATIONS
e6b0: 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 36 34 7d  :.**.** {U12264}
e6c0: 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
e6d0: 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
e6e0: 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
e6f0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
e700: 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
e710: 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74  while [sqlite3_t
e720: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
e730: 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
e740: 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20  the value.**    
e750: 20 20 20 20 20 20 72 65 74 75 72 6e 65 64 20 69        returned i
e760: 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
e770: 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
e780: 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
e790: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
e7a0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
e7b0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
e7c0: 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
e7d0: 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b 46 31 32  nning Query {F12
e7e0: 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  270}.**.** This 
e7f0: 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
e800: 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
e810: 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
e820: 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
e830: 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
e840: 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
e850: 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
e860: 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
e870: 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
e880: 73 65 20 74 6f 20 61 6e 20 75 73 65 72 20 61 63  se to an user ac
e890: 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
e8a0: 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
e8b0: 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
e8c0: 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
e8d0: 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
e8e0: 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
e8f0: 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
e900: 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73 61 66 65  **.** It is safe
e910: 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
e920: 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
e930: 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
e940: 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
e950: 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
e960: 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
e970: 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
e980: 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
e990: 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
e9a0: 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
e9b0: 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
e9c0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
e9d0: 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
e9e0: 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
e9f0: 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
ea00: 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
ea10: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 53 51 4c  .**.** If an SQL
ea20: 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65   operation is ve
ea30: 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68  ry nearly finish
ea40: 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ed at the time w
ea50: 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  hen.** sqlite3_i
ea60: 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61  nterrupt() is ca
ea70: 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69  lled, then it mi
ea80: 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20  ght not have an 
ea90: 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74  opportunity.** t
eaa0: 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64  o be interrupted
eab0: 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69   and might conti
eac0: 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  nue to completio
ead0: 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 53 51 4c 20  n..**.** An SQL 
eae0: 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69  operation that i
eaf0: 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69  s interrupted wi
eb00: 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
eb10: 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a  E_INTERRUPT]..**
eb20: 20 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70   If the interrup
eb30: 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ted SQL operatio
eb40: 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20  n is an INSERT, 
eb50: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
eb60: 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73  E.** that is ins
eb70: 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20  ide an explicit 
eb80: 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
eb90: 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61  n the entire tra
eba0: 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c  nsaction.** will
ebb0: 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
ebc0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a  automatically..*
ebd0: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
ebe0: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
ebf0: 28 29 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  () has no effect
ec00: 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
ec10: 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
ec20: 74 61 72 74 65 64 20 61 66 74 65 72 20 73 71 6c  tarted after sql
ec30: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
ec40: 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
ec50: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
ec60: 2a 20 7b 46 31 32 32 37 31 7d 20 54 68 65 20 5b  * {F12271} The [
ec70: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
ec80: 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  t()] interface w
ec90: 69 6c 6c 20 66 6f 72 63 65 20 61 6c 6c 20 72 75  ill force all ru
eca0: 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  nning.**        
ecb0: 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73    SQL statements
ecc0: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
ecd0: 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
ece0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
ecf0: 20 20 20 20 20 20 20 20 20 20 74 6f 20 68 61 6c            to hal
ed00: 74 20 61 66 74 65 72 20 70 72 6f 63 65 73 73 69  t after processi
ed10: 6e 67 20 61 74 20 6d 6f 73 74 20 6f 6e 65 20 61  ng at most one a
ed20: 64 64 69 74 69 6f 6e 61 6c 20 72 6f 77 20 6f 66  dditional row of
ed30: 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   data..**.** {F1
ed40: 32 32 37 32 7d 20 41 6e 79 20 53 51 4c 20 73 74  2272} Any SQL st
ed50: 61 74 65 6d 65 6e 74 20 74 68 61 74 20 69 73 20  atement that is 
ed60: 69 6e 74 65 72 72 75 70 74 65 64 20 62 79 20 5b  interrupted by [
ed70: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
ed80: 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  t()].**         
ed90: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
eda0: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
edb0: 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f  .**.** LIMITATIO
edc0: 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 37  NS:.**.** {U1227
edd0: 39 7d 20 49 66 20 74 68 65 20 64 61 74 61 62 61  9} If the databa
ede0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
edf0: 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69  oses while [sqli
ee00: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
ee10: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
ee20: 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
ee30: 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
ee40: 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76  ely happen..*/.v
ee50: 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
ee60: 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
ee70: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
ee80: 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
ee90: 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
eea0: 49 73 20 43 6f 6d 70 6c 65 74 65 20 7b 46 31 30  Is Complete {F10
eeb0: 35 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  510}.**.** These
eec0: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
eed0: 65 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64  eful for command
eee0: 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
eef0: 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
ef00: 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
ef10: 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
ef20: 74 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65  to form complete
ef30: 20 61 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74   a SQL statement
ef40: 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
ef50: 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
ef60: 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
ef70: 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
ef80: 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
ef90: 70 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20  parsing.  These 
efa0: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
efb0: 74 72 75 65 20 69 66 20 74 68 65 20 69 6e 70 75  true if the inpu
efc0: 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
efd0: 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
efe0: 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
eff0: 6e 74 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74  nt.  A statement
f000: 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
f010: 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
f020: 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
f030: 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
f040: 6e 64 20 69 73 20 6e 6f 74 20 61 20 66 72 61 67  nd is not a frag
f050: 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45  ment of a.** CRE
f060: 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
f070: 65 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f  ement.  Semicolo
f080: 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65  ns that are embe
f090: 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73  dded within.** s
f0a0: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f  tring literals o
f0b0: 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66  r quoted identif
f0c0: 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d  ier names or com
f0d0: 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ments are not.**
f0e0: 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b   independent tok
f0f0: 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61  ens (they are pa
f100: 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20  rt of the token 
f110: 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72  in which they ar
f120: 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61  e.** embedded) a
f130: 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63  nd thus do not c
f140: 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d  ount as a statem
f150: 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ent terminator..
f160: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
f170: 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
f180: 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
f190: 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
f1a0: 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
f1b0: 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
f1c0: 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
f1d0: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
f1e0: 2a 20 7b 46 31 30 35 31 31 7d 20 54 68 65 20 73  * {F10511} The s
f1f0: 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
f200: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
f210: 6d 70 6c 65 74 65 31 36 28 29 20 66 75 6e 63 74  mplete16() funct
f220: 69 6f 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ions.**         
f230: 20 72 65 74 75 72 6e 20 74 72 75 65 20 28 6e 6f   return true (no
f240: 6e 2d 7a 65 72 6f 29 20 69 66 20 61 6e 64 20 6f  n-zero) if and o
f250: 6e 6c 79 20 69 66 20 74 68 65 20 6c 61 73 74 20  nly if the last 
f260: 6e 6f 6e 2d 77 68 69 74 65 73 70 61 63 65 0a 2a  non-whitespace.*
f270: 2a 20 20 20 20 20 20 20 20 20 20 74 6f 6b 65 6e  *          token
f280: 20 69 6e 20 74 68 65 69 72 20 69 6e 70 75 74 20   in their input 
f290: 69 73 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74  is a semicolon t
f2a0: 68 61 74 20 69 73 20 6e 6f 74 20 69 6e 20 62 65  hat is not in be
f2b0: 74 77 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20  tween.**        
f2c0: 20 20 74 68 65 20 42 45 47 49 4e 20 61 6e 64 20    the BEGIN and 
f2d0: 45 4e 44 20 6f 66 20 61 20 43 52 45 41 54 45 20  END of a CREATE 
f2e0: 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e  TRIGGER statemen
f2f0: 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54  t..**.** LIMITAT
f300: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 30  IONS:.**.** {U10
f310: 35 31 32 7d 20 54 68 65 20 69 6e 70 75 74 20 74  512} The input t
f320: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  o sqlite3_comple
f330: 74 65 28 29 20 6d 75 73 74 20 62 65 20 61 20 7a  te() must be a z
f340: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
f350: 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38  *          UTF-8
f360: 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
f370: 55 31 30 35 31 33 7d 20 54 68 65 20 69 6e 70 75  U10513} The inpu
f380: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  t to sqlite3_com
f390: 70 6c 65 74 65 31 36 28 29 20 6d 75 73 74 20 62  plete16() must b
f3a0: 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
f3b0: 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
f3c0: 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
f3d0: 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
f3e0: 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
f3f0: 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
f400: 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e  t char *sql);.in
f410: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
f420: 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
f430: 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
f440: 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
f450: 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
f460: 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
f470: 59 20 45 72 72 6f 72 73 20 7b 46 31 32 33 31 30  Y Errors {F12310
f480: 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
f490: 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
f4a0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68  back function th
f4b0: 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
f4c0: 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  ked whenever.** 
f4d0: 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
f4e0: 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74  de to open a dat
f4f0: 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74  abase table that
f500: 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
f510: 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
f520: 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20  s locked..**.** 
f530: 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
f540: 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
f550: 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
f560: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
f570: 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
f580: 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
f590: 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
f5a0: 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
f5b0: 2e 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61  . If the busy ca
f5c0: 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
f5d0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
f5e0: 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65  callback will be
f5f0: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
f600: 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  o arguments..**.
f610: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
f620: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e  ument to the han
f630: 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
f640: 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
f650: 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
f660: 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
f670: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
f680: 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 54  sy_handler().  T
f690: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
f6a0: 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e  nt to.** the han
f6b0: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
f6c0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
f6d0: 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
f6e0: 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
f6f0: 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66  * been invoked f
f700: 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20  or this locking 
f710: 65 76 65 6e 74 2e 20 20 49 66 20 74 68 65 0a 2a  event.  If the.*
f720: 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
f730: 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
f740: 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
f750: 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
f760: 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
f770: 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
f780: 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
f790: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
f7a0: 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
f7b0: 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c  d..** If the cal
f7c0: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
f7d0: 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
f7e0: 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
f7f0: 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
f800: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72  the database for
f810: 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65   reading and the
f820: 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
f830: 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
f840: 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
f850: 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
f860: 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
f870: 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
f880: 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
f890: 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
f8a0: 2e 20 49 66 20 53 51 4c 69 74 65 20 64 65 74 65  . If SQLite dete
f8b0: 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
f8c0: 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
f8d0: 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
f8e0: 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
f8f0: 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
f900: 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
f910: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
f920: 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  * or [SQLITE_IOE
f930: 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74  RR_BLOCKED] inst
f940: 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
f950: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
f960: 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
f970: 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
f980: 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
f990: 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
f9a0: 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
f9b0: 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
f9c0: 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
f9d0: 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
f9e0: 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
f9f0: 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
fa00: 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
fa10: 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
fa20: 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
fa30: 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
fa40: 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
fa50: 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
fa60: 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
fa70: 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
fa80: 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
fa90: 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
faa0: 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
fab0: 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
fac0: 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
fad0: 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
fae0: 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
faf0: 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
fb00: 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
fb10: 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
fb20: 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
fb30: 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
fb40: 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
fb50: 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
fb60: 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
fb70: 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
fb80: 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
fb90: 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
fba0: 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
fbb0: 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
fbc0: 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
fbd0: 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
fbe0: 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
fbf0: 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
fc00: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
fc10: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65   [SQLITE_BUSY] e
fc20: 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65  rror is converte
fc30: 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45  d to [SQLITE_IOE
fc40: 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77  RR_BLOCKED].** w
fc50: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e  hen SQLite is in
fc60: 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61   the middle of a
fc70: 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69   large transacti
fc80: 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65  on where all the
fc90: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c  .** changes will
fca0: 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68   not fit into th
fcb0: 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68  e in-memory cach
fcc0: 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a  e.  SQLite will.
fcd0: 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20  ** already hold 
fce0: 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20  a RESERVED lock 
fcf0: 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
fd00: 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65  file, but it nee
fd10: 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ds.** to promote
fd20: 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58   this lock to EX
fd30: 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20  CLUSIVE so that 
fd40: 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63  it can spill cac
fd50: 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f  he.** pages into
fd60: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
fd70: 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20  le without harm 
fd80: 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a  to concurrent.**
fd90: 20 72 65 61 64 65 72 73 2e 20 20 49 66 20 69 74   readers.  If it
fda0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72   is unable to pr
fdb0: 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20  omote the lock, 
fdc0: 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  then the in-memo
fdd0: 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c  ry.** cache will
fde0: 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69   be left in an i
fdf0: 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74  nconsistent stat
fe00: 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72  e and so the err
fe10: 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72  or.** code is pr
fe20: 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20  omoted from the 
fe30: 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67  relatively benig
fe40: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
fe50: 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  to.** the more s
fe60: 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f  evere [SQLITE_IO
fe70: 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54  ERR_BLOCKED].  T
fe80: 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70  his error code p
fe90: 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63  romotion.** forc
fea0: 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20  es an automatic 
feb0: 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  rollback of the 
fec0: 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68  changes.  See th
fed0: 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63  e.** <a href="/c
fee0: 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f  vstrac/wiki?p=Co
fef0: 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
ff00: 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20  gBusyError">.** 
ff10: 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
ff20: 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e  ingBusyError</a>
ff30: 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61   wiki page for a
ff40: 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77   discussion of w
ff50: 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d  hy.** this is im
ff60: 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  portant..**.** T
ff70: 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
ff80: 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
ff90: 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66  andler defined f
ffa0: 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  or each.** [data
ffb0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
ffc0: 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77  .  Setting a new
ffd0: 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c   busy handler cl
ffe0: 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76  ears any.** prev
fff0: 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c  iously set handl
10000 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 63  er.  Note that c
10010 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
10020 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
10030 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74  ** will also set
10040 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75   or clear the bu
10050 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
10060 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
10070 0a 2a 2a 20 7b 46 31 32 33 31 31 7d 20 54 68 65  .** {F12311} The
10080 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
10090 61 6e 64 6c 65 72 28 29 5d 20 66 75 6e 63 74 69  andler()] functi
100a0 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20  on replaces the 
100b0 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
100c0 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
100d0 6b 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  k in the databas
100e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65  e connection ide
100f0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 31  ntified by the 1
10100 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  st.**          p
10110 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 61 20  arameter with a 
10120 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
10130 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
10140 68 65 20 32 6e 64 20 61 6e 64 20 33 72 64 0a 2a  he 2nd and 3rd.*
10150 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
10160 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  eters..**.** {F1
10170 32 33 31 32 7d 20 54 68 65 20 64 65 66 61 75 6c  2312} The defaul
10180 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  t busy handler f
10190 6f 72 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  or new database 
101a0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 69 73 20 4e  connections is N
101b0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33  ULL..**.** {F123
101c0 31 34 7d 20 57 68 65 6e 20 74 77 6f 20 6f 72 20  14} When two or 
101d0 6d 6f 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  more database co
101e0 6e 6e 65 63 74 69 6f 6e 20 73 68 61 72 65 20 61  nnection share a
101f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
10200 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
10210 72 65 64 5f 63 61 63 68 65 20 7c 20 63 6f 6d 6d  red_cache | comm
10220 6f 6e 20 63 61 63 68 65 5d 2c 0a 2a 2a 20 20 20  on cache],.**   
10230 20 20 20 20 20 20 20 74 68 65 20 62 75 73 79 20         the busy 
10240 68 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20  handler for the 
10250 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10260 69 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20 75 73  ion currently us
10270 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
10280 74 68 65 20 63 61 63 68 65 20 69 73 20 69 6e 76  the cache is inv
10290 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 63 61  oked when the ca
102a0 63 68 65 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  che encounters a
102b0 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   lock..**.** {F1
102c0 32 33 31 36 7d 20 49 66 20 61 20 62 75 73 79 20  2316} If a busy 
102d0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
102e0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
102f0 68 65 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69  hen the SQLite i
10300 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20  nterface.**     
10310 20 20 20 20 20 74 68 61 74 20 70 72 6f 76 6f 6b       that provok
10320 65 64 20 74 68 65 20 6c 6f 63 6b 69 6e 67 20 65  ed the locking e
10330 76 65 6e 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  vent will return
10340 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
10350 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 38 7d 20 53  **.** {F12318} S
10360 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
10370 65 73 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  es the busy hand
10380 6c 65 72 20 77 69 74 68 20 74 77 6f 20 61 72 67  ler with two arg
10390 75 6d 65 6e 74 73 20 77 68 69 63 68 0a 2a 2a 20  uments which.** 
103a0 20 20 20 20 20 20 20 20 20 61 72 65 20 61 20 63           are a c
103b0 6f 70 79 20 6f 66 20 74 68 65 20 70 6f 69 6e 74  opy of the point
103c0 65 72 20 73 75 70 70 6c 69 65 64 20 62 79 20 74  er supplied by t
103d0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
103e0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
103f0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
10400 6e 64 6c 65 72 28 29 5d 20 61 6e 64 20 61 20 63  ndler()] and a c
10410 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62  ount of the numb
10420 65 72 20 6f 66 20 70 72 69 6f 72 0a 2a 2a 20 20  er of prior.**  
10430 20 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69          invocati
10440 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 73 79 20  ons of the busy 
10450 68 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20  handler for the 
10460 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65  same locking eve
10470 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41  nt..**.** LIMITA
10480 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31  TIONS:.**.** {U1
10490 32 33 31 39 7d 20 41 20 62 75 73 79 20 68 61 6e  2319} A busy han
104a0 64 6c 65 72 20 73 68 6f 75 6c 64 20 6e 6f 74 20  dler should not 
104b0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
104c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
104d0 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 70 72            or [pr
104e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
104f0 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  ] that invoked t
10500 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
10510 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
10520 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
10530 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
10540 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29  id*,int), void*)
10550 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10560 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69  F: Set A Busy Ti
10570 6d 65 6f 75 74 20 7b 46 31 32 33 34 30 7d 0a 2a  meout {F12340}.*
10580 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
10590 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65  e sets a [sqlite
105a0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c  3_busy_handler |
105b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74   busy handler] t
105c0 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f  hat sleeps.** fo
105d0 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d  r a specified am
105e0 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65  ount of time whe
105f0 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63  n a table is loc
10600 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65  ked.  The handle
10610 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20  r.** will sleep 
10620 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
10630 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d  ntil at least "m
10640 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
10650 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68  of sleeping.** h
10660 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e  ave accumulated.
10670 20 7b 46 31 32 33 34 33 7d 20 41 66 74 65 72 20   {F12343} After 
10680 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
10690 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
106a0 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
106b0 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
106c0 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
106d0 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
106e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
106f0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
10700 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a  R_BLOCKED]..**.*
10710 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72  * Calling this r
10720 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
10730 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
10740 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
10750 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20  ro.** turns off 
10760 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  all busy handler
10770 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63  s..**.** There c
10780 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
10790 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
107a0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
107b0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
107c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61  onnection] any a
107d0 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
107e0 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
107f0 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
10800 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
10810 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
10820 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
10830 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
10840 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
10850 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
10860 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
10870 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
10880 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 31  S:.**.** {F12341
10890 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
108a0 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 66  usy_timeout()] f
108b0 75 6e 63 74 69 6f 6e 20 6f 76 65 72 72 69 64 65  unction override
108c0 73 20 61 6e 79 20 70 72 69 6f 72 0a 2a 2a 20 20  s any prior.**  
108d0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
108e0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
108f0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 62 75 73   or [sqlite3_bus
10900 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 73 65 74  y_handler()] set
10910 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ting.**         
10920 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
10930 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10940 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 33 7d  ..**.** {F12343}
10950 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   If the 2nd para
10960 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
10970 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
10980 5d 20 69 73 20 6c 65 73 73 20 74 68 61 6e 0a 2a  ] is less than.*
10990 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 65 71  *          or eq
109a0 75 61 6c 20 74 6f 20 7a 65 72 6f 2c 20 74 68 65  ual to zero, the
109b0 6e 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  n the busy handl
109c0 65 72 20 69 73 20 63 6c 65 61 72 65 64 20 73 6f  er is cleared so
109d0 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20   that.**        
109e0 20 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74    all subsequent
109f0 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 73 20   locking events 
10a00 69 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74 75  immediately retu
10a10 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
10a20 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 34 7d  ..**.** {F12344}
10a30 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   If the 2nd para
10a40 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
10a50 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
10a60 5d 20 69 73 20 61 20 70 6f 73 69 74 69 76 65 0a  ] is a positive.
10a70 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
10a80 65 72 20 4e 2c 20 74 68 65 6e 20 61 20 62 75 73  er N, then a bus
10a90 79 20 68 61 6e 64 6c 65 72 20 69 73 20 73 65 74  y handler is set
10aa0 20 74 68 61 74 20 72 65 70 65 61 74 65 64 6c 79   that repeatedly
10ab0 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20   calls.**       
10ac0 20 20 20 74 68 65 20 78 53 6c 65 65 70 28 29 20     the xSleep() 
10ad0 6d 65 74 68 6f 64 20 69 6e 20 74 68 65 20 56 46  method in the VF
10ae0 53 20 69 6e 74 65 72 66 61 63 65 20 75 6e 74 69  S interface unti
10af0 6c 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20  l either the.** 
10b00 20 20 20 20 20 20 20 20 20 6c 6f 63 6b 20 63 6c           lock cl
10b10 65 61 72 73 20 6f 72 20 75 6e 74 69 6c 20 74 68  ears or until th
10b20 65 20 63 75 6d 75 6c 61 74 69 76 65 20 73 6c 65  e cumulative sle
10b30 65 70 20 74 69 6d 65 20 72 65 70 6f 72 74 65 64  ep time reported
10b40 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20   back.**        
10b50 20 20 62 79 20 78 53 6c 65 65 70 28 29 20 65 78    by xSleep() ex
10b60 63 65 65 64 73 20 4e 20 6d 69 6c 6c 69 73 65 63  ceeds N millisec
10b70 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  onds..*/.int sql
10b80 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
10b90 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
10ba0 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ms);../*.** CAPI
10bb0 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63  3REF: Convenienc
10bc0 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52  e Routines For R
10bd0 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 20 7b  unning Queries {
10be0 46 31 32 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 44 65  F12370}.**.** De
10bf0 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
10c00 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
10c10 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
10c20 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
10c30 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
10c40 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
10c50 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
10c60 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
10c70 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
10c80 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
10c90 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
10ca0 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
10cb0 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
10cc0 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
10cd0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
10ce0 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
10cf0 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
10d00 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
10d10 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
10d20 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
10d30 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
10d40 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
10d50 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
10d60 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
10d70 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
10d80 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
10d90 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
10da0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
10db0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
10dc0 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
10dd0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
10de0 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
10df0 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
10e00 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
10e10 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
10e20 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
10e30 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
10e40 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
10e50 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
10e60 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
10e70 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
10e80 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
10e90 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
10ea0 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
10eb0 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
10ec0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
10ed0 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
10ee0 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
10ef0 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
10f00 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
10f10 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
10f20 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
10f30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
10f40 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
10f50 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
10f60 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
10f70 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
10f80 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
10f90 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
10fa0 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
10fb0 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
10fc0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
10fd0 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
10fe0 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
10ff0 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
11000 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
11010 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  able()]..**.** A
11020 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
11030 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
11040 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
11050 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
11060 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
11070 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
11080 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
11090 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
110a0 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
110b0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
110c0 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
110d0 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
110e0 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
110f0 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
11100 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
11110 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
11120 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
11130 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
11140 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
11150 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
11160 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
11170 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
11180 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
11190 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
111a0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
111b0 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
111c0 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
111d0 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
111e0 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
111f0 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
11200 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
11210 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
11220 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
11230 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
11240 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
11250 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
11260 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
11270 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
11280 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
11290 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
112a0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
112b0 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
112c0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
112d0 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
112e0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
112f0 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
11300 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
11310 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
11320 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
11330 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
11340 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
11350 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
11360 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
11370 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
11380 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
11390 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
113a0 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
113b0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
113c0 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
113d0 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  s 2nd parameter.
113e0 20 20 49 74 20 72 65 74 75 72 6e 73 20 61 20 72    It returns a r
113f0 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
11400 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
11410 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
11420 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
11430 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69 6e  After the callin
11440 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 66  g function has f
11450 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
11460 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68 6f  e result, it sho
11470 75 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 65 20  uld.** pass the 
11480 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 72  pointer to the r
11490 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 73  esult table to s
114a0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
114b0 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a  e() in order to.
114c0 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  ** release the m
114d0 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d  emory that was m
114e0 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73  alloced.  Becaus
114f0 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65  e of the way the
11500 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
11510 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77  loc()] happens w
11520 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65  ithin sqlite3_ge
11530 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63  t_table(), the c
11540 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  alling.** functi
11550 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20  on must not try 
11560 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  to call [sqlite3
11570 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c  _free()] directl
11580 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c  y.  Only.** [sql
11590 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
115a0 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65  )] is able to re
115b0 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
115c0 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61   properly and sa
115d0 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fely..**.** The 
115e0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
115f0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
11600 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20   implemented as 
11610 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  a wrapper around
11620 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
11630 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74  c()].  The sqlit
11640 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72  e3_get_table() r
11650 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20  outine does not 
11660 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  have access.** t
11670 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64  o any internal d
11680 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f  ata structures o
11690 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73  f SQLite.  It us
116a0 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c  es only the publ
116b0 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ic.** interface 
116c0 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41  defined here.  A
116d0 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c  s a consequence,
116e0 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
116f0 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61  ur in the.** wra
11700 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69  pper layer outsi
11710 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e  de of the intern
11720 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  al [sqlite3_exec
11730 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74  ()] call are not
11740 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e  .** reflected in
11750 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
11760 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
11770 72 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71 6c  rcode()] or [sql
11780 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
11790 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
117a0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 31 7d  :.**.** {F12371}
117b0 20 49 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 67   If a [sqlite3_g
117c0 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 61 69 6c  et_table()] fail
117d0 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  s a memory alloc
117e0 61 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20  ation, then.**  
117f0 20 20 20 20 20 20 20 20 69 74 20 66 72 65 65 73          it frees
11800 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
11810 65 20 75 6e 64 65 72 20 63 6f 6e 73 74 72 75 63  e under construc
11820 74 69 6f 6e 2c 20 61 62 6f 72 74 73 20 74 68 65  tion, aborts the
11830 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 71 75 65  .**          que
11840 72 79 20 69 6e 20 70 72 6f 63 65 73 73 2c 20 73  ry in process, s
11850 6b 69 70 73 20 61 6e 79 20 73 75 62 73 65 71 75  kips any subsequ
11860 65 6e 74 20 71 75 65 72 69 65 73 2c 20 73 65 74  ent queries, set
11870 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
11880 20 20 2a 72 65 73 75 6c 74 70 20 6f 75 74 70 75    *resultp outpu
11890 74 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c  t pointer to NUL
118a0 4c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 5b 53  L and returns [S
118b0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
118c0 0a 2a 2a 20 7b 46 31 32 33 37 33 7d 20 49 66 20  .** {F12373} If 
118d0 74 68 65 20 6e 63 6f 6c 75 6d 6e 20 70 61 72 61  the ncolumn para
118e0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
118f0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
11900 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20  s not NULL.**   
11910 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c         then [sql
11920 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
11930 5d 20 77 72 69 74 65 73 20 74 68 65 20 6e 75 6d  ] writes the num
11940 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
11950 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
11960 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20    result set of 
11970 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a  the query into *
11980 6e 63 6f 6c 75 6d 6e 20 69 66 20 74 68 65 20 71  ncolumn if the q
11990 75 65 72 79 20 69 73 0a 2a 2a 20 20 20 20 20 20  uery is.**      
119a0 20 20 20 20 73 75 63 63 65 73 73 66 75 6c 20 28      successful (
119b0 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  if the function 
119c0 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f  returns SQLITE_O
119d0 4b 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37  K)..**.** {F1237
119e0 34 7d 20 49 66 20 74 68 65 20 6e 72 6f 77 20 70  4} If the nrow p
119f0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
11a00 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
11a10 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a  ] is not NULL.**
11a20 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b            then [
11a30 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
11a40 65 28 29 5d 20 77 72 69 74 65 73 20 74 68 65 20  e()] writes the 
11a50 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69  number of rows i
11a60 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
11a70 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20    result set of 
11a80 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a  the query into *
11a90 6e 72 6f 77 20 69 66 20 74 68 65 20 71 75 65 72  nrow if the quer
11aa0 79 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  y is.**         
11ab0 20 73 75 63 63 65 73 73 66 75 6c 20 28 69 66 20   successful (if 
11ac0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  the function ret
11ad0 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 29 2e  urns SQLITE_OK).
11ae0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 36 7d 20  .**.** {F12376} 
11af0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  The [sqlite3_get
11b00 5f 74 61 62 6c 65 28 29 5d 20 66 75 6e 63 74 69  _table()] functi
11b10 6f 6e 20 73 65 74 73 20 69 74 73 20 2a 6e 63 6f  on sets its *nco
11b20 6c 75 6d 6e 20 76 61 6c 75 65 20 74 6f 20 74 68  lumn value to th
11b30 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
11b40 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
11b50 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
11b60 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69  t of the query i
11b70 6e 20 74 68 65 20 73 71 6c 0a 2a 2a 20 20 20 20  n the sql.**    
11b80 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2c        parameter,
11b90 20 6f 72 20 74 6f 20 7a 65 72 6f 20 69 66 20 74   or to zero if t
11ba0 68 65 20 71 75 65 72 79 20 69 6e 20 73 71 6c 20  he query in sql 
11bb0 68 61 73 20 61 6e 20 65 6d 70 74 79 20 72 65 73  has an empty res
11bc0 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20  ult set..*/.int 
11bd0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
11be0 65 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20  e(.  sqlite3*,  
11bf0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e             /* An
11c00 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
11c10 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
11c20 73 71 6c 2c 20 20 20 20 20 20 2f 2a 20 53 51 4c  sql,      /* SQL
11c30 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
11c40 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 52   */.  char ***pR
11c50 65 73 75 6c 74 2c 20 20 20 20 20 20 2f 2a 20 52  esult,      /* R
11c60 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
11c70 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 72  ery */.  int *nr
11c80 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  ow,            /
11c90 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
11ca0 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
11cb0 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e  here */.  int *n
11cc0 63 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 20  column,         
11cd0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
11ce0 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
11cf0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
11d00 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
11d10 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
11d20 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
11d30 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .);.void sqlite3
11d40 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
11d50 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
11d60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
11d70 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
11d80 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
11d90 20 7b 46 31 37 34 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F17400}.**.** 
11da0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
11db0 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66  re workalikes of
11dc0 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
11dd0 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
11de0 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
11df0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
11e00 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ry..**.** The sq
11e10 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
11e20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
11e30 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
11e40 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
11e50 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
11e60 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
11e70 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
11e80 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
11e90 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
11ea0 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
11eb0 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
11ec0 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
11ed0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 20  ite3_free()].   
11ee0 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
11ef0 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
11f00 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
11f10 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20  e3_malloc()] is 
11f20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
11f30 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
11f40 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
11f50 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
11f60 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74  ..**.** In sqlit
11f70 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
11f80 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
11f90 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
11fa0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
11fb0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
11fc0 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
11fd0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
11fe0 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
11ff0 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
12000 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
12010 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
12020 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
12030 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
12040 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
12050 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
12060 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
12070 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
12080 6e 70 72 69 6e 74 66 28 29 2e 20 20 54 68 69 73  nprintf().  This
12090 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
120a0 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
120b0 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
120c0 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
120d0 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
120e0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
120f0 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20   Note also that 
12100 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
12110 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
12120 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
12130 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
12140 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
12150 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
12160 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
12170 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 20 20  to the buffer.  
12180 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
12190 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
121a0 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
121b0 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
121c0 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
121d0 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
121e0 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
121f0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
12200 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
12210 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
12220 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
12230 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
12240 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 74  .** As long as t
12250 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69  he buffer size i
12260 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
12270 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70  ero, sqlite3_snp
12280 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61  rintf().** guara
12290 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62  ntees that the b
122a0 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20  uffer is always 
122b0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
122c0 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70    The first.** p
122d0 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
122e0 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
122f0 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
12300 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
12310 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
12320 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
12330 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
12340 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
12350 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
12360 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
12370 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
12380 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
12390 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
123a0 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
123b0 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
123c0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
123d0 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
123e0 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
123f0 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
12400 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28  he usual printf(
12410 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  ) formatting opt
12420 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20  ions apply.  In 
12430 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a  addition, there.
12440 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20  ** is are "%q", 
12450 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f  "%Q", and "%z" o
12460 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ptions..**.** Th
12470 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
12480 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
12490 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
124a0 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74   a null-terminat
124b0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
124c0 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
124d0 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
124e0 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
124f0 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
12500 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
12510 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
12520 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
12530 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  l.  By doubling 
12540 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
12550 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
12560 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
12570 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
12580 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
12590 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
125a0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
125b0 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
125c0 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
125d0 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
125e0 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
125f0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
12600 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
12610 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
12620 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
12630 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
12640 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
12650 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
12660 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
12670 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
12680 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
12690 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
126a0 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
126b0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
126c0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
126d0 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
126e0 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
126f0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
12700 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
12710 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
12720 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
12730 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
12740 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
12750 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
12760 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
12770 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
12780 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
12790 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
127a0 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
127b0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
127c0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
127d0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
127e0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
127f0 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
12800 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
12810 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
12820 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
12830 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
12840 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
12850 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
12860 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
12870 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
12880 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
12890 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
128a0 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
128b0 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
128c0 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
128d0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
128e0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
128f0 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
12900 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
12910 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
12920 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
12930 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
12940 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
12950 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
12960 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
12970 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
12980 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  * The %Q option 
12990 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
129a0 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
129b0 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
129c0 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
129d0 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
129e0 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
129f0 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
12a00 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
12a10 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
12a20 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
12a30 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
12a40 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
12a50 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
12a60 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 20   single quotes) 
12a70 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
12a80 25 51 20 6f 70 74 69 6f 6e 2e 20 7b 45 4e 44 7d  %Q option. {END}
12a90 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
12aa0 65 2c 0a 2a 2a 20 6f 6e 65 20 63 6f 75 6c 64 20  e,.** one could 
12ab0 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
12ac0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
12ad0 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
12ae0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
12af0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
12b00 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
12b10 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
12b20 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
12b30 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
12b40 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
12b50 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
12b60 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
12b70 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
12b80 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
12b90 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
12ba0 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
12bb0 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
12bc0 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
12bd0 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
12be0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
12bf0 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
12c00 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
12c10 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73  exactly like "%s
12c20 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  " with the.** ad
12c30 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
12c40 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
12c50 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
12c60 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
12c70 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
12c80 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
12c90 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
12ca0 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a  t string. {END}.
12cb0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
12cc0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 33 7d  :.**.** {F17403}
12cd0 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
12ce0 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 20 5b 73  printf()] and [s
12cf0 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
12d00 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  )] interfaces.**
12d10 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72             retur
12d20 6e 20 65 69 74 68 65 72 20 70 6f 69 6e 74 65 72  n either pointer
12d30 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
12d40 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
12d50 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 20 20  gs held in.**   
12d60 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 6f          memory o
12d70 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
12d80 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
12d90 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  or NULL pointers
12da0 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
12db0 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
12dc0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 61  te3_malloc()] fa
12dd0 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34  ils..**.** {F174
12de0 30 36 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  06}  The [sqlite
12df0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e  3_snprintf()] in
12e00 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20 61  terface writes a
12e10 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
12e20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 55 54  .**           UT
12e30 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 74 6f 20  F-8 string into 
12e40 74 68 65 20 62 75 66 66 65 72 20 70 6f 69 6e 74  the buffer point
12e50 65 64 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ed to by the sec
12e60 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
12e70 20 20 20 20 20 20 20 20 20 20 20 70 72 6f 76 69             provi
12e80 64 65 64 20 74 68 61 74 20 74 68 65 20 66 69 72  ded that the fir
12e90 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
12ea0 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
12eb0 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 37  o..**.** {F17407
12ec0 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
12ed0 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65  snprintf()] inte
12ee0 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 77  rface does not w
12ef0 72 69 74 65 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a  rite slots of.**
12f00 20 20 20 20 20 20 20 20 20 20 20 69 74 73 20 6f             its o
12f10 75 74 70 75 74 20 62 75 66 66 65 72 20 28 74 68  utput buffer (th
12f20 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
12f30 65 72 29 20 6f 75 74 73 69 64 65 20 74 68 65 20  er) outside the 
12f40 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  range.**        
12f50 20 20 20 6f 66 20 30 20 74 68 72 6f 75 67 68 20     of 0 through 
12f60 4e 2d 31 20 28 77 68 65 72 65 20 4e 20 69 73 20  N-1 (where N is 
12f70 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
12f80 74 65 72 29 0a 2a 2a 20 20 20 20 20 20 20 20 20  ter).**         
12f90 20 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20    regardless of 
12fa0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
12fb0 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20  e string.**     
12fc0 20 20 20 20 20 20 72 65 71 75 65 73 74 65 64 20        requested 
12fd0 62 79 20 74 68 65 20 66 6f 72 6d 61 74 20 73 70  by the format sp
12fe0 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2f 0a  ecification..*/.
12ff0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70  char *sqlite3_mp
13000 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
13010 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  *,...);.char *sq
13020 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
13030 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
13040 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ist);.char *sqli
13050 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
13060 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
13070 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  r*, ...);../*.**
13080 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
13090 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62  y Allocation Sub
130a0 73 79 73 74 65 6d 20 7b 46 31 37 33 30 30 7d 0a  system {F17300}.
130b0 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
130c0 20 63 6f 72 65 20 20 75 73 65 73 20 74 68 65 73   core  uses thes
130d0 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73  e three routines
130e0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
130f0 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20  own.** internal 
13100 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13110 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20  n needs. "Core" 
13120 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
13130 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73  sentence.** does
13140 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65   not include ope
13150 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
13160 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65  ecific VFS imple
13170 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a  mentation.  The.
13180 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75  ** Windows VFS u
13190 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f  ses native mallo
131a0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
131b0 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f  or some operatio
131c0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ns..**.** The sq
131d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
131e0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
131f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c   pointer to a bl
13200 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  ock.** of memory
13210 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
13220 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65  s in length, whe
13230 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61  re N is the para
13240 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c  meter..** If sql
13250 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
13260 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69   unable to obtai
13270 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65  n sufficient fre
13280 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20  e.** memory, it 
13290 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
132a0 6f 69 6e 74 65 72 2e 20 20 49 66 20 74 68 65 20  ointer.  If the 
132b0 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
132c0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
132d0 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
132e0 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
132f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
13300 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
13310 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61  ointer..**.** Ca
13320 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  lling sqlite3_fr
13330 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ee() with a poin
13340 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72  ter previously r
13350 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
13360 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
13370 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
13380 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61  c() releases tha
13390 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74  t memory so.** t
133a0 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20  hat it might be 
133b0 72 65 75 73 65 64 2e 20 20 54 68 65 20 73 71 6c  reused.  The sql
133c0 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
133d0 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
133e0 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
133f0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
13400 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
13410 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
13420 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
13430 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
13440 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
13450 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
13460 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
13470 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
13480 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
13490 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
134a0 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
134b0 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
134c0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
134d0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
134e0 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
134f0 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
13500 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
13510 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
13520 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
13530 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
13540 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
13550 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
13560 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
13570 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
13580 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
13590 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
135a0 69 74 65 33 5f 66 72 65 65 28 29 2e 0a 2a 2a 0a  ite3_free()..**.
135b0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
135c0 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61  ealloc() interfa
135d0 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
135e0 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
135f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13600 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73  on to be at leas
13610 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65  t N bytes, where
13620 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63   N is the.** sec
13630 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
13640 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  The memory alloc
13650 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69  ation to be resi
13660 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74  zed is the first
13670 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20  .** parameter.  
13680 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  If the first par
13690 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
136a0 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
136b0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
136c0 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
136d0 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
136e0 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
136f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
13700 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
13710 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
13720 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
13730 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20  oc()..** If the 
13740 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
13750 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
13760 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
13770 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
13780 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
13790 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
137a0 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
137b0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29   sqlite3_free(P)
137c0 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20   where P is the 
137d0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
137e0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
137f0 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  oc()..** sqlite3
13800 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
13810 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
13820 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
13830 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
13840 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
13850 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75  ze or NULL if su
13860 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
13870 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
13880 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20 73  ** If M is the s
13890 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
138a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
138b0 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
138c0 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
138d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
138e0 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
138f0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
13900 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
13910 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
13920 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69  oc() and the pri
13930 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
13940 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71   freed..** If sq
13950 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
13960 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68  returns NULL, th
13970 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  en the prior all
13980 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f  ocation.** is no
13990 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  t freed..**.** T
139a0 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  he memory return
139b0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ed by sqlite3_ma
139c0 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74  lloc() and sqlit
139d0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
139e0 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
139f0 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
13a00 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
13a10 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  . {END}.**.** Th
13a20 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d  e default implem
13a30 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
13a40 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13a50 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73 65 73  n subsystem uses
13a60 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29  .** the malloc()
13a70 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
13a80 66 72 65 65 28 29 20 70 72 6f 76 69 64 65 64 20  free() provided 
13a90 62 79 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  by the standard 
13aa0 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b 46  C library..** {F
13ab0 31 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20  17382} However, 
13ac0 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
13ad0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
13ae0 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f  * SQLITE_MEMORY_
13af0 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20  SIZE=<i>NNN</i> 
13b00 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
13b10 61 63 72 6f 20 28 77 68 65 72 65 20 3c 69 3e 4e  acro (where <i>N
13b20 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e 20  NN</i>.** is an 
13b30 69 6e 74 65 67 65 72 29 2c 20 74 68 65 6e 20 53  integer), then S
13b40 51 4c 69 74 65 20 63 72 65 61 74 65 20 61 20 73  QLite create a s
13b50 74 61 74 69 63 20 61 72 72 61 79 20 6f 66 20 61  tatic array of a
13b60 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e  t least.** <i>NN
13b70 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73  N</i> bytes in s
13b80 69 7a 65 20 61 6e 64 20 75 73 65 73 20 74 68 61  ize and uses tha
13b90 74 20 61 72 72 61 79 20 66 6f 72 20 61 6c 6c 20  t array for all 
13ba0 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 0a 2a  of its dynamic.*
13bb0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
13bc0 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d  ion needs. {END}
13bd0 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d    Additional mem
13be0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70  ory allocator op
13bf0 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 20  tions.** may be 
13c00 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
13c10 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
13c20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
13c30 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
13c40 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
13c50 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
13c60 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
13c70 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
13c80 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
13c90 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
13ca0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
13cb0 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
13cc0 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
13cd0 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
13ce0 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
13cf0 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
13d00 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
13d10 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
13d20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
13d30 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f  ** The Windows O
13d40 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
13d50 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73  r calls.** the s
13d60 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
13d70 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
13d80 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
13d90 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
13da0 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
13db0 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
13dc0 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
13dd0 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
13de0 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
13df0 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
13e00 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a  cular Windows.**
13e10 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
13e20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
13e30 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74  n errors are det
13e40 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68  ected, but.** th
13e50 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ey are reported 
13e60 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
13e70 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
13e80 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
13e90 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
13ea0 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
13eb0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
13ec0 2a 2a 20 7b 46 31 37 33 30 33 7d 20 20 54 68 65  ** {F17303}  The
13ed0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13ee0 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (N)] interface r
13ef0 65 74 75 72 6e 73 20 65 69 74 68 65 72 20 61 20  eturns either a 
13f00 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20  pointer to.**   
13f10 20 20 20 20 20 20 20 20 61 20 6e 65 77 6c 79 20          a newly 
13f20 63 68 65 63 6b 65 64 2d 6f 75 74 20 62 6c 6f 63  checked-out bloc
13f30 6b 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  k of at least N 
13f40 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a  bytes of memory.
13f50 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61  **           tha
13f60 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67  t is 8-byte alig
13f70 6e 65 64 2c 20 6f 72 20 69 74 20 72 65 74 75 72  ned, or it retur
13f80 6e 73 20 4e 55 4c 4c 20 69 66 20 69 74 20 69 73  ns NULL if it is
13f90 20 75 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20   unable.**      
13fa0 20 20 20 20 20 74 6f 20 66 75 6c 66 69 6c 6c 20       to fulfill 
13fb0 74 68 65 20 72 65 71 75 65 73 74 2e 0a 2a 2a 0a  the request..**.
13fc0 2a 2a 20 7b 46 31 37 33 30 34 7d 20 20 54 68 65  ** {F17304}  The
13fd0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13fe0 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (N)] interface r
13ff0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
14000 69 6e 74 65 72 20 69 66 0a 2a 2a 20 20 20 20 20  inter if.**     
14010 20 20 20 20 20 20 4e 20 69 73 20 6c 65 73 73 20        N is less 
14020 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
14030 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31   zero..**.** {F1
14040 37 33 30 35 7d 20 20 54 68 65 20 5b 73 71 6c 69  7305}  The [sqli
14050 74 65 33 5f 66 72 65 65 28 50 29 5d 20 69 6e 74  te3_free(P)] int
14060 65 72 66 61 63 65 20 72 65 6c 65 61 73 65 73 20  erface releases 
14070 6d 65 6d 6f 72 79 20 70 72 65 76 69 6f 75 73 6c  memory previousl
14080 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  y.**           r
14090 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
140a0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
140b0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
140c0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  loc()],.**      
140d0 20 20 20 20 20 6d 61 6b 69 6e 67 20 69 74 20 61       making it a
140e0 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 72 65 75  vailable for reu
140f0 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30  se..**.** {F1730
14100 36 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  6}  A call to [s
14110 71 6c 69 74 65 33 5f 66 72 65 65 28 4e 55 4c 4c  qlite3_free(NULL
14120 29 5d 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  )] is a harmless
14130 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 46   no-op..**.** {F
14140 31 37 33 31 30 7d 20 20 41 20 63 61 6c 6c 20 74  17310}  A call t
14150 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  o [sqlite3_reall
14160 6f 63 28 30 2c 4e 29 5d 20 69 73 20 65 71 75 69  oc(0,N)] is equi
14170 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c  valent to a call
14180 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f  .**           to
14190 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
141a0 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  (N)]..**.** {F17
141b0 33 31 32 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20  312}  A call to 
141c0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
141d0 28 50 2c 30 29 5d 20 69 73 20 65 71 75 69 76 61  (P,0)] is equiva
141e0 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a  lent to a call.*
141f0 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b  *           to [
14200 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d  sqlite3_free(P)]
14210 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 35 7d  ..**.** {F17315}
14220 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
14230 65 20 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  e uses [sqlite3_
14240 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
14250 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a  te3_realloc()],.
14260 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 6e 64  **           and
14270 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
14280 5d 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  ] for all of its
14290 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
142a0 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  on and.**       
142b0 20 20 20 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e      deallocation
142c0 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46   needs..**.** {F
142d0 31 37 33 31 38 7d 20 20 54 68 65 20 5b 73 71 6c  17318}  The [sql
142e0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e  ite3_realloc(P,N
142f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
14300 75 72 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f  urns either a po
14310 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  inter.**        
14320 20 20 20 74 6f 20 61 20 62 6c 6f 63 6b 20 6f 66     to a block of
14330 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 6d 65 6d   checked-out mem
14340 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ory of at least 
14350 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 0a  N bytes in size.
14360 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61  **           tha
14370 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67  t is 8-byte alig
14380 6e 65 64 2c 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ned, or a NULL p
14390 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ointer..**.** {F
143a0 31 37 33 32 31 7d 20 20 57 68 65 6e 20 5b 73 71  17321}  When [sq
143b0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c  lite3_realloc(P,
143c0 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  N)] returns a no
143d0 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
143e0 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20  it first.**     
143f0 20 20 20 20 20 20 63 6f 70 69 65 73 20 74 68 65        copies the
14400 20 66 69 72 73 74 20 4b 20 62 79 74 65 73 20 6f   first K bytes o
14410 66 20 63 6f 6e 74 65 6e 74 20 66 72 6f 6d 20 50  f content from P
14420 20 69 6e 74 6f 20 74 68 65 20 6e 65 77 6c 79 0a   into the newly.
14430 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 6c 6c  **           all
14440 6f 63 61 74 65 64 20 62 6c 6f 63 6b 2c 20 77 68  ocated block, wh
14450 65 72 65 20 4b 20 69 73 20 74 68 65 20 6c 65 73  ere K is the les
14460 73 65 72 20 6f 66 20 4e 20 61 6e 64 20 74 68 65  ser of N and the
14470 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 20 20 20 20   size of.**     
14480 20 20 20 20 20 20 74 68 65 20 62 75 66 66 65 72        the buffer
14490 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32   P..**.** {F1732
144a0 32 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65  2}  When [sqlite
144b0 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20  3_realloc(P,N)] 
144c0 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55  returns a non-NU
144d0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66  LL pointer, it f
144e0 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  irst.**         
144f0 20 20 72 65 6c 65 61 73 65 73 20 74 68 65 20 62    releases the b
14500 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b  uffer P..**.** {
14510 46 31 37 33 32 33 7d 20 20 57 68 65 6e 20 5b 73  F17323}  When [s
14520 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50  qlite3_realloc(P
14530 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 4e 55 4c  ,N)] returns NUL
14540 4c 2c 20 74 68 65 20 62 75 66 66 65 72 20 50 20  L, the buffer P 
14550 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  is.**           
14560 6e 6f 74 20 6d 6f 64 69 66 69 65 64 20 6f 72 20  not modified or 
14570 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
14580 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a  LIMITATIONS:.**.
14590 2a 2a 20 7b 55 31 37 33 35 30 7d 20 20 54 68 65  ** {U17350}  The
145a0 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
145b0 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
145c0 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
145d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
145e0 2a 20 20 20 20 20 20 20 20 20 20 20 6d 75 73 74  *           must
145f0 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
14600 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
14610 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
14620 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20   prior.**       
14630 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f      invocation o
14640 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
14650 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
14660 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74  _realloc()] that
14670 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20   have.**        
14680 20 20 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20     not yet been 
14690 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
146a0 7b 55 31 37 33 35 31 7d 20 20 54 68 65 20 61 70  {U17351}  The ap
146b0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
146c0 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
146d0 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
146e0 20 20 20 20 20 20 20 20 20 20 61 20 62 6c 6f 63            a bloc
146f0 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
14700 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
14710 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
14720 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
14730 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
14740 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
14750 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  ]..*/.void *sqli
14760 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
14770 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
14780 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
14790 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
147a0 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  _free(void*);../
147b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
147c0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
147d0 53 74 61 74 69 73 74 69 63 73 20 7b 46 31 37 33  Statistics {F173
147e0 37 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  70}.**.** SQLite
147f0 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20   provides these 
14800 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66  two interfaces f
14810 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20  or reporting on 
14820 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66  the status.** of
14830 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   the [sqlite3_ma
14840 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
14850 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b  3_free()], and [
14860 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
14870 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20  )].** routines, 
14880 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62  which form the b
14890 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
148a0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
148b0 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  tem..**.** INVAR
148c0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
148d0 37 33 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  7371} The [sqlit
148e0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
148f0 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
14900 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
14910 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  bytes.**        
14920 20 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72    of memory curr
14930 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
14940 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
14950 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 0a 2a  not freed)..**.*
14960 2a 20 7b 46 31 37 33 37 33 7d 20 54 68 65 20 5b  * {F17373} The [
14970 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
14980 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74  ighwater()] rout
14990 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
149a0 6d 61 78 69 6d 75 6d 0a 2a 2a 20 20 20 20 20 20  maximum.**      
149b0 20 20 20 20 76 61 6c 75 65 20 6f 66 20 5b 73 71      value of [sq
149c0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
149d0 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68  d()] since the h
149e0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
149f0 2a 20 20 20 20 20 20 20 20 20 20 77 61 73 20 6c  *          was l
14a00 61 73 74 20 72 65 73 65 74 2e 0a 2a 2a 0a 2a 2a  ast reset..**.**
14a10 20 7b 46 31 37 33 37 34 7d 20 54 68 65 20 76 61   {F17374} The va
14a20 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
14a30 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
14a40 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
14a50 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
14a60 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
14a70 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e  er()] include an
14a80 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 20 20  y overhead.**   
14a90 20 20 20 20 20 20 20 61 64 64 65 64 20 62 79 20         added by 
14aa0 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d  SQLite in its im
14ab0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
14ac0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14ad0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
14ae0 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
14af0 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
14b00 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
14b10 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 20  tem library.**  
14b20 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65 73          routines
14b30 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d   that [sqlite3_m
14b40 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c  alloc()] may cal
14b50 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 35  l..**.** {F17375
14b60 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67  } The memory hig
14b70 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  h-water mark is 
14b80 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72  reset to the cur
14b90 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  rent value of.**
14ba0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
14bb0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
14bc0 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
14bd0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
14be0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
14bf0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
14c00 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72  ghwater()] is tr
14c10 75 65 2e 20 20 54 68 65 20 76 61 6c 75 65 20 72  ue.  The value r
14c20 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20  eturned.**      
14c30 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f      by [sqlite3_
14c40 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
14c50 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
14c60 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20  -water mark.**  
14c70 20 20 20 20 20 20 20 20 70 72 69 6f 72 20 74 6f          prior to
14c80 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73   the reset..*/.s
14c90 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
14ca0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
14cb0 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f  (void);.sqlite3_
14cc0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
14cd0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
14ce0 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
14cf0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
14d00 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75  Pseudo-Random Nu
14d10 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 20 7b  mber Generator {
14d20 46 31 37 33 39 30 7d 0a 2a 2a 0a 2a 2a 20 53 51  F17390}.**.** SQ
14d30 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  Lite contains a 
14d40 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
14d50 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65  udo-random numbe
14d60 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e  r generator (PRN
14d70 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65  G) used to.** se
14d80 6c 65 63 74 20 72 61 6e 64 6f 6d 20 52 4f 57 49  lect random ROWI
14d90 44 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  Ds when insertin
14da0 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
14db0 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
14dc0 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
14dd0 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
14de0 69 62 6c 65 20 52 4f 57 49 44 2e 20 20 54 68 65  ible ROWID.  The
14df0 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
14e00 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
14e10 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
14e20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
14e30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
14e40 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
14e50 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
14e60 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
14e70 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
14e80 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
14e90 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  s..**.** A call 
14ea0 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
14eb0 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
14ec0 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
14ed0 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a  o buffer P..**.*
14ee0 2a 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65  * The first time
14ef0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
14f00 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72   invoked (either
14f10 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62   internally or b
14f20 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  y.** the applica
14f30 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69  tion) the PRNG i
14f40 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72  s seeded using r
14f50 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
14f60 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78  ed.** from the x
14f70 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f  Randomness metho
14f80 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
14f90 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
14fa0 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c  bject..** On all
14fb0 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
14fc0 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65  cations, the pse
14fd0 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
14fe0 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69  s generated.** i
14ff0 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69  nternally and wi
15000 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74  thout recourse t
15010 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
15020 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a  fs] xRandomness.
15030 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a  ** method..**.**
15040 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
15050 2a 2a 20 7b 46 31 37 33 39 32 7d 20 54 68 65 20  ** {F17392} The 
15060 5b 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e  [sqlite3_randomn
15070 65 73 73 28 4e 2c 50 29 5d 20 69 6e 74 65 72 66  ess(N,P)] interf
15080 61 63 65 20 77 72 69 74 65 73 20 4e 20 62 79 74  ace writes N byt
15090 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  es of.**        
150a0 20 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70    high-quality p
150b0 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73  seudo-randomness
150c0 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
150d0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
150e0 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
150f0 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
15100 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
15110 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
15120 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
15130 73 20 7b 46 31 32 35 30 30 7d 0a 2a 2a 0a 2a 2a  s {F12500}.**.**
15140 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
15150 67 69 73 74 65 72 73 20 61 20 61 75 74 68 6f 72  gisters a author
15160 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
15170 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
15180 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
15190 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
151a0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
151b0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
151c0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
151d0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
151e0 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
151f0 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
15200 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
15210 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
15220 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
15230 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
15240 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
15250 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
15260 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
15270 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 41  pare16_v2()].  A
15280 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
15290 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
152a0 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
152b0 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
152c0 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
152d0 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
152e0 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
152f0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
15300 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
15310 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
15320 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
15330 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61 75 74  llowed.  The aut
15340 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
15350 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
15360 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
15370 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
15380 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
15390 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
153a0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
153b0 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
153c0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
153d0 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
153e0 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
153f0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
15400 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
15410 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
15420 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
15430 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
15440 72 6f 72 2e 20 20 49 66 20 74 68 65 20 61 75 74  ror.  If the aut
15450 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
15460 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
15470 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
15480 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
15490 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
154a0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
154b0 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
154c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
154d0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
154e0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
154f0 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
15500 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
15510 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
15520 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
15530 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
15540 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
15550 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
15560 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
15570 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
15580 2e 20 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  .  When the call
15590 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
155a0 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
155b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
155c0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
155d0 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
155e0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
155f0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
15600 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
15610 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
15620 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
15630 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
15640 64 2e 20 20 49 66 20 74 68 65 20 61 75 74 68 6f  d.  If the autho
15650 72 69 7a 65 72 20 63 6f 64 65 20 69 73 20 5b 53  rizer code is [S
15660 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
15670 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
15680 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
15690 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
156a0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
156b0 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
156c0 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
156d0 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
156e0 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
156f0 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
15700 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
15710 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
15720 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
15730 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
15740 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
15750 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
15760 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
15770 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
15780 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
15790 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
157a0 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
157b0 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 0a   of a table..**.
157c0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
157d0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
157e0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
157f0 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
15800 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
15810 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
15820 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
15830 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
15840 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
15850 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
15860 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
15870 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
15880 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
15890 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
158a0 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
158b0 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
158c0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 54 68 65   authorized. The
158d0 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
158e0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
158f0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
15900 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
15910 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
15920 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
15930 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
15940 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
15950 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
15960 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  zed..**.** An au
15970 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
15980 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
15990 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
159a0 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
159b0 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
159c0 74 72 75 73 74 65 64 0a 2a 2a 20 73 6f 75 72 63  trusted.** sourc
159d0 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
159e0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
159f0 65 6e 74 73 20 64 6f 20 6e 6f 74 20 74 72 79 20  ents do not try 
15a00 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 0a 2a  to access data.*
15a10 2a 20 74 68 61 74 20 74 68 65 79 20 61 72 65 20  * that they are 
15a20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
15a30 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
15a40 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 0a 2a   do not try to.*
15a50 2a 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  * execute malici
15a60 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
15a70 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
15a80 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
15a90 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
15aa0 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
15ab0 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
15ac0 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
15ad0 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
15ae0 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
15af0 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
15b00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
15b10 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
15b20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
15b30 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
15b40 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
15b50 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
15b60 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
15b70 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
15b80 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
15b90 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
15ba0 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
15bb0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
15bc0 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
15bd0 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
15be0 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
15bf0 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
15c00 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
15c10 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
15c20 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
15c30 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
15c40 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
15c50 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
15c60 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
15c70 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
15c80 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
15c90 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
15ca0 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
15cb0 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
15cc0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
15cd0 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
15ce0 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
15cf0 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
15d00 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  ** Only a single
15d10 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20   authorizer can 
15d20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61  be in place on a
15d30 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15d40 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d  tion.** at a tim
15d50 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  e.  Each call to
15d60 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
15d70 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65  horizer override
15d80 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75  s the.** previou
15d90 73 20 63 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65  s call.  Disable
15da0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
15db0 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
15dc0 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
15dd0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
15de0 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
15df0 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4e  default..**.** N
15e00 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
15e10 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
15e20 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
15e30 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
15e40 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
15e50 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
15e60 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
15e70 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
15e80 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
15e90 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
15ea0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
15eb0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
15ec0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
15ed0 35 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  501} The [sqlite
15ee0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
15ef0 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  (D,...)] interfa
15f00 63 65 20 72 65 67 69 73 74 65 72 73 20 61 0a 2a  ce registers a.*
15f10 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 68 6f  *          autho
15f20 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
15f30 69 74 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ith database con
15f40 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  nection D..**.**
15f50 20 7b 46 31 32 35 30 32 7d 20 54 68 65 20 61 75   {F12502} The au
15f60 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
15f70 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
15f80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
15f90 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  re.**          b
15fa0 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 2e 0a 2a  eing compiled..*
15fb0 2a 0a 2a 2a 20 7b 46 31 32 35 30 33 7d 20 49 66  *.** {F12503} If
15fc0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
15fd0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
15fe0 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
15ff0 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20   than.**        
16000 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45    [SQLITE_IGNORE
16010 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
16020 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
16030 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
16040 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f     the [sqlite3_
16050 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
16060 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
16070 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20   that caused.** 
16080 20 20 20 20 20 20 20 20 20 74 68 65 20 61 75 74           the aut
16090 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
160a0 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61   to run shall fa
160b0 69 6c 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20  il with an.**   
160c0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45         [SQLITE_E
160d0 52 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65  RROR] error code
160e0 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69   and an appropri
160f0 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  ate error messag
16100 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 34  e..**.** {F12504
16110 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74 68 6f  } When the autho
16120 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
16130 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
16140 4b 5d 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  K], the operatio
16150 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65  n.**          de
16160 73 63 72 69 62 65 64 20 69 73 20 70 72 6f 63 65  scribed is proce
16170 73 73 65 64 20 6e 6f 72 6d 61 6c 6c 79 2e 0a 2a  ssed normally..*
16180 2a 0a 2a 2a 20 7b 46 31 32 35 30 35 7d 20 57 68  *.** {F12505} Wh
16190 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  en the authorize
161a0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
161b0 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
161c0 2c 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  , the.**        
161d0 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61    [sqlite3_prepa
161e0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
161f0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
16200 20 63 61 75 73 65 64 20 74 68 65 0a 2a 2a 20 20   caused the.**  
16210 20 20 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a          authoriz
16220 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72  er callback to r
16230 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a  un shall fail.**
16240 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 61            with a
16250 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
16260 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
16270 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
16280 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 70  .**          exp
16290 6c 61 69 6e 69 6e 67 20 74 68 61 74 20 61 63 63  laining that acc
162a0 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 0a 2a  ess is denied..*
162b0 2a 0a 2a 2a 20 7b 46 31 32 35 30 36 7d 20 49 66  *.** {F12506} If
162c0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
162d0 63 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61  code (the 2nd pa
162e0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
162f0 75 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20  uthorizer.**    
16300 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20        callback) 
16310 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
16320 20 61 6e 64 20 74 68 65 20 61 75 74 68 6f 72 69   and the authori
16330 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
16340 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
16350 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
16360 2c 20 74 68 65 6e 20 74 68 65 20 70 72 65 70 61  , then the prepa
16370 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73  red statement is
16380 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 0a   constructed to.
16390 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73 65  **          inse
163a0 72 74 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  rt a NULL value 
163b0 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
163c0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
163d0 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
163e0 20 20 20 20 20 20 20 20 20 62 65 65 6e 20 72 65           been re
163f0 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
16400 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
16410 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35  ned..**.** {F125
16420 30 37 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f  07} If the autho
16430 72 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20  rizer code (the 
16440 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
16450 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a   the authorizer.
16460 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
16470 62 61 63 6b 29 20 69 73 20 61 6e 79 74 68 69 6e  back) is anythin
16480 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
16490 4c 49 54 45 5f 52 45 41 44 5d 2c 20 74 68 65 6e  LITE_READ], then
164a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72  .**          a r
164b0 65 74 75 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45  eturn of [SQLITE
164c0 5f 49 47 4e 4f 52 45 5d 20 68 61 73 20 74 68 65  _IGNORE] has the
164d0 20 73 61 6d 65 20 65 66 66 65 63 74 20 61 73 20   same effect as 
164e0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2e 0a 2a  [SQLITE_DENY]..*
164f0 2a 0a 2a 2a 20 7b 46 31 32 35 31 30 7d 20 54 68  *.** {F12510} Th
16500 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
16510 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
16520 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
16530 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20  a copy of.**    
16540 20 20 20 20 20 20 74 68 65 20 74 68 69 72 64 20        the third 
16550 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
16560 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
16570 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
16580 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  rface..**.** {F1
16590 32 35 31 31 7d 20 54 68 65 20 73 65 63 6f 6e 64  2511} The second
165a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
165b0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
165c0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20   integer.**     
165d0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50       [SQLITE_COP
165e0 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
165f0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
16600 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
16610 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
16620 20 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a    to be authoriz
16630 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31  ed..**.** {F1251
16640 32 7d 20 54 68 65 20 74 68 69 72 64 20 74 68 72  2} The third thr
16650 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
16660 65 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c  eters to the cal
16670 6c 62 61 63 6b 20 61 72 65 0a 2a 2a 20 20 20 20  lback are.**    
16680 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
16690 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
166a0 61 74 20 63 6f 6e 74 61 69 6e 0a 2a 2a 20 20 20  at contain.**   
166b0 20 20 20 20 20 20 20 61 64 64 69 74 69 6f 6e 61         additiona
166c0 6c 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  l details about 
166d0 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
166e0 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
166f0 2a 2a 20 7b 46 31 32 35 32 30 7d 20 45 61 63 68  ** {F12520} Each
16700 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
16710 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
16720 28 29 5d 20 6f 76 65 72 72 69 64 65 73 0a 2a 2a  ()] overrides.**
16730 20 20 20 20 20 20 20 20 20 20 61 6e 79 20 70 72            any pr
16740 65 76 69 6f 75 73 6c 79 20 69 6e 73 74 61 6c 6c  eviously install
16750 65 64 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  ed authorizer..*
16760 2a 0a 2a 2a 20 7b 46 31 32 35 32 31 7d 20 41 20  *.** {F12521} A 
16770 4e 55 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20  NULL authorizer 
16780 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75  means that no au
16790 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20  thorization.**  
167a0 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b          callback
167b0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
167c0 2a 2a 20 7b 46 31 32 35 32 32 7d 20 54 68 65 20  ** {F12522} The 
167d0 64 65 66 61 75 6c 74 20 61 75 74 68 6f 72 69 7a  default authoriz
167e0 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69  er is NULL..*/.i
167f0 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  nt sqlite3_set_a
16800 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c  uthorizer(.  sql
16810 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78  ite3*,.  int (*x
16820 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  Auth)(void*,int,
16830 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
16840 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
16850 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  ar*,const char*)
16860 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44  ,.  void *pUserD
16870 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ata.);../*.** CA
16880 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
16890 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 20  er Return Codes 
168a0 7b 46 31 32 35 39 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12590}.**.** T
168b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
168c0 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
168d0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
168e0 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
168f0 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
16900 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
16910 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
16920 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
16930 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
16940 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
16950 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
16960 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
16970 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
16980 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
16990 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
169a0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
169b0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
169c0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
169d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
169e0 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
169f0 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
16a00 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
16a10 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
16a20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
16a30 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
16a40 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
16a50 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
16a60 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
16a70 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
16a80 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
16a90 20 7b 46 31 32 35 35 30 7d 0a 2a 2a 0a 2a 2a 20   {F12550}.**.** 
16aa0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
16ab0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
16ac0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
16ad0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
16ae0 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
16af0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
16b00 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53  horize certain S
16b10 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
16b20 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
16b30 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
16b40 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
16b50 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
16b60 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
16b70 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
16b80 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
16b90 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
16ba0 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
16bb0 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
16bc0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
16bd0 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
16be0 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
16bf0 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
16c00 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
16c10 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
16c20 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a  ation is to be.*
16c30 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
16c40 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
16c50 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
16c60 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
16c70 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
16c80 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
16c90 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
16ca0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
16cb0 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
16cc0 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
16cd0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
16ce0 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 70 61  ter.  The 5th pa
16cf0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
16d00 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  * authorizer cal
16d10 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d  lback is the nam
16d20 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
16d30 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e ("main", "temp
16d40 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61  ",.** etc.) if a
16d50 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65 20  pplicable.  The 
16d60 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
16d70 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
16d80 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
16d90 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
16da0 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
16db0 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
16dc0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
16dd0 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
16de0 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
16df0 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
16e00 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
16e10 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
16e20 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
16e30 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
16e40 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 31 7d 20  .**.** {F12551} 
16e50 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
16e60 65 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 20 20  eter to an.**   
16e70 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
16e80 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
16e90 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
16ea0 62 61 63 6b 5d 20 69 73 20 61 6c 77 61 79 73 20  back] is always 
16eb0 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20  an integer.**   
16ec0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43         [SQLITE_C
16ed0 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  OPY | authorizer
16ee0 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
16ef0 69 66 69 65 73 20 77 68 61 74 20 61 63 74 69 6f  ifies what actio
16f00 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  n.**          is
16f10 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65   being authorize
16f20 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 32  d..**.** {F12552
16f30 7d 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74  } The 3rd and 4t
16f40 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
16f50 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
16f60 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
16f70 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
16f80 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  ization callback
16f90 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  ].**          wi
16fa0 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
16fb0 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
16fc0 6e 67 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 20  ng on which.**  
16fd0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
16fe0 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65  COPY | authorize
16ff0 72 20 63 6f 64 65 5d 20 69 73 20 75 73 65 64 20  r code] is used 
17000 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
17010 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
17020 46 31 32 35 35 33 7d 20 54 68 65 20 35 74 68 20  F12553} The 5th 
17030 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
17040 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
17050 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
17060 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
17070 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74  r callback] is t
17080 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he name.**      
17090 20 20 20 20 6f 66 20 74 68 65 20 64 61 74 61 62      of the datab
170a0 61 73 65 20 28 65 78 61 6d 70 6c 65 3a 20 22 6d  ase (example: "m
170b0 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65 74  ain", "temp", et
170c0 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
170d0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 34  e..**.** {F12554
170e0 7d 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65  } The 6th parame
170f0 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ter to the.**   
17100 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
17110 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
17120 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17130 62 61 63 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d  back] is the nam
17140 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
17150 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
17160 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
17170 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
17180 62 6c 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  ble for.**      
17190 20 20 20 20 74 68 65 20 61 63 63 65 73 73 20 61      the access a
171a0 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
171b0 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
171c0 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
171d0 79 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20  y from.**       
171e0 20 20 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c     top-level SQL
171f0 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   code..*/./*****
17200 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
17210 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
17220 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
17230 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
17240 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
17250 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
17260 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
17270 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
17280 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
17290 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
172a0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
172b0 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
172c0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
172d0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
172e0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
172f0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
17300 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
17310 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
17320 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
17330 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17340 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
17350 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
17360 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
17370 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
17380 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17390 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
173a0 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
173b0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
173c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
173d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
173e0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
173f0 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
17400 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
17410 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
17420 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17430 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
17440 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
17450 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
17460 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
17470 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17480 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
17490 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
174a0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
174b0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
174c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
174d0 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
174e0 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
174f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
17500 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
17510 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17520 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
17530 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
17540 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
17550 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
17560 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
17570 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
17580 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
17590 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
175a0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
175b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
175c0 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
175d0 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
175e0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
175f0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
17600 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
17610 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
17620 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
17630 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
17640 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
17650 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
17660 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
17670 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
17680 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
17690 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
176a0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
176b0 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
176c0 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
176d0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
176e0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
176f0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
17700 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
17710 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
17720 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
17730 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
17740 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
17750 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
17760 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
17770 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
17780 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
17790 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
177a0 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
177b0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
177c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
177d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
177e0 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
177f0 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
17800 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
17810 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
17820 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
17830 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
17840 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
17850 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
17860 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
17870 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17880 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
17890 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
178a0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
178b0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
178c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
178d0 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
178e0 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
178f0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
17900 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
17910 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17920 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
17930 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
17940 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
17950 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
17960 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17970 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
17980 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
17990 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
179a0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
179b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
179c0 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
179d0 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
179e0 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
179f0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
17a00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
17a10 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
17a20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
17a30 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
17a40 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
17a50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
17a60 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
17a70 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
17a80 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
17a90 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
17aa0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
17ab0 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
17ac0 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
17ad0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
17ae0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
17af0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
17b00 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
17b10 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
17b20 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
17b30 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
17b40 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
17b50 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
17b60 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
17b70 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
17b80 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
17b90 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
17ba0 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
17bb0 31 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20  1   /* Function 
17bc0 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20  Name   NULL     
17bd0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
17be0 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
17bf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
17c00 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
17c10 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
17c20 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
17c30 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
17c40 75 6e 63 74 69 6f 6e 73 20 7b 46 31 32 32 38 30  unctions {F12280
17c50 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  }.**.** These ro
17c60 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
17c70 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
17c80 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
17c90 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
17ca0 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
17cb0 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
17cc0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
17cd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ..**.** The call
17ce0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
17cf0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
17d00 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
17d10 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
17d20 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
17d30 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
17d40 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
17d50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
17d60 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  ]..** The callba
17d70 63 6b 20 72 65 74 75 72 6e 73 20 61 20 55 54 46  ck returns a UTF
17d80 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
17d90 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
17da0 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 74 68 65  t text.** as the
17db0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
17dc0 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
17dd0 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 63  g.  Additional c
17de0 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a  allbacks occur.*
17df0 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
17e00 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
17e10 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
17e20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
17e30 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
17e40 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
17e50 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
17e60 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
17e70 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  r..**.** The cal
17e80 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
17e90 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
17ea0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
17eb0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
17ec0 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
17ed0 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 54 68  nt finishes.  Th
17ee0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
17ef0 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
17f00 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
17f10 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
17f20 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
17f30 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
17f40 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
17f50 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
17f60 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54   to run..**.** T
17f70 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  he sqlite3_profi
17f80 6c 65 28 29 20 41 50 49 20 69 73 20 63 75 72 72  le() API is curr
17f90 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
17fa0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
17fb0 64 0a 2a 2a 20 69 73 20 73 75 62 6a 65 63 74 20  d.** is subject 
17fc0 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72 65 6d  to change or rem
17fd0 6f 76 61 6c 20 69 6e 20 61 20 66 75 74 75 72 65  oval in a future
17fe0 20 72 65 6c 65 61 73 65 2e 0a 2a 2a 0a 2a 2a 20   release..**.** 
17ff0 54 68 65 20 74 72 69 67 67 65 72 20 72 65 70 6f  The trigger repo
18000 72 74 69 6e 67 20 66 65 61 74 75 72 65 20 6f 66  rting feature of
18010 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62   the trace callb
18020 61 63 6b 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ack is considere
18030 64 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61  d.** experimenta
18040 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74  l and is subject
18050 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72 65   to change or re
18060 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65 20  moval in future 
18070 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 20 46 75 74  releases..** Fut
18080 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
18090 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
180a0 6f 20 61 64 64 20 6e 65 77 20 74 72 61 63 65 20  o add new trace 
180b0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6e 76 6f  callback.** invo
180c0 63 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  cations..**.** I
180d0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
180e0 20 7b 46 31 32 32 38 31 7d 20 54 68 65 20 63 61   {F12281} The ca
180f0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
18100 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73  registered by [s
18110 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20  qlite3_trace()] 
18120 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  is.**          w
18130 68 65 6e 65 76 65 72 20 61 6e 20 53 51 4c 20 73  henever an SQL s
18140 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
18150 65 67 69 6e 73 20 74 6f 20 65 78 65 63 75 74 65  egins to execute
18160 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
18170 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 69 67   whenever a trig
18180 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 20 66  ger subprogram f
18190 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20 72  irst begins to r
181a0 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38  un..**.** {F1228
181b0 32 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  2} Each call to 
181c0 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
181d0 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 20  ] overrides the 
181e0 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20  previously.**   
181f0 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
18200 64 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  d trace callback
18210 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 33 7d  ..**.** {F12283}
18220 20 41 20 4e 55 4c 4c 20 74 72 61 63 65 20 63 61   A NULL trace ca
18230 6c 6c 62 61 63 6b 20 64 69 73 61 62 6c 65 73 20  llback disables 
18240 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b  tracing..**.** {
18250 46 31 32 32 38 34 7d 20 54 68 65 20 66 69 72 73  F12284} The firs
18260 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
18270 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  e trace callback
18280 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   is a copy of.**
18290 20 20 20 20 20 20 20 20 20 20 74 68 65 20 70 6f            the po
182a0 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20  inter which was 
182b0 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74  the 3rd argument
182c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   to [sqlite3_tra
182d0 63 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ce()]..**.** {F1
182e0 32 32 38 35 7d 20 54 68 65 20 73 65 63 6f 6e 64  2285} The second
182f0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
18300 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
18310 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  is a.**         
18320 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
18330 20 55 54 46 38 20 73 74 72 69 6e 67 20 63 6f 6e   UTF8 string con
18340 74 61 69 6e 69 6e 67 20 74 68 65 20 6f 72 69 67  taining the orig
18350 69 6e 61 6c 20 74 65 78 74 0a 2a 2a 20 20 20 20  inal text.**    
18360 20 20 20 20 20 20 6f 66 20 74 68 65 20 53 51 4c        of the SQL
18370 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74   statement as it
18380 20 77 61 73 20 70 61 73 73 65 64 20 69 6e 74 6f   was passed into
18390 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
183a0 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20  e_v2()].**      
183b0 20 20 20 20 6f 72 20 74 68 65 20 65 71 75 69 76      or the equiv
183c0 61 6c 65 6e 74 2c 20 6f 72 20 61 6e 20 53 51 4c  alent, or an SQL
183d0 20 63 6f 6d 6d 65 6e 74 20 69 6e 64 69 63 61 74   comment indicat
183e0 69 6e 67 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  ing the beginnin
183f0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  g.**          of
18400 20 61 20 74 72 69 67 67 65 72 20 73 75 62 70 72   a trigger subpr
18410 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ogram..**.** {F1
18420 32 32 38 37 7d 20 54 68 65 20 63 61 6c 6c 62 61  2287} The callba
18430 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
18440 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69 74  stered by [sqlit
18450 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 69 73  e3_profile()] is
18460 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20   invoked.**     
18470 20 20 20 20 20 61 73 20 65 61 63 68 20 53 51 4c       as each SQL
18480 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
18490 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  hes..**.** {F122
184a0 38 38 7d 20 54 68 65 20 66 69 72 73 74 20 70 61  88} The first pa
184b0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70  rameter to the p
184c0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
184d0 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  is a copy of.** 
184e0 20 20 20 20 20 20 20 20 20 74 68 65 20 33 72 64           the 3rd
184f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
18500 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
18510 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 39  ]..**.** {F12289
18520 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  } The second par
18530 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72  ameter to the pr
18540 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69  ofile callback i
18550 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
18560 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
18570 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 61  UTF-8 string tha
18580 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 63  t contains the c
18590 6f 6d 70 6c 65 74 65 20 74 65 78 74 20 6f 66 0a  omplete text of.
185a0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
185b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
185c0 20 69 74 20 77 61 73 20 70 72 6f 63 65 73 73 65   it was processe
185d0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  d by [sqlite3_pr
185e0 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20  epare_v2()].**  
185f0 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 65          or the e
18600 71 75 69 76 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a  quivalent..**.**
18610 20 7b 46 31 32 32 39 30 7d 20 54 68 65 20 74 68   {F12290} The th
18620 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
18630 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c   the profile cal
18640 6c 62 61 63 6b 20 69 73 20 61 6e 20 65 73 74 69  lback is an esti
18650 6d 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  mate.**         
18660 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
18670 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 20 6f 66  f nanoseconds of
18680 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
18690 20 72 65 71 75 69 72 65 64 20 74 6f 0a 2a 2a 20   required to.** 
186a0 20 20 20 20 20 20 20 20 20 72 75 6e 20 74 68 65           run the
186b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
186c0 72 6f 6d 20 73 74 61 72 74 20 74 6f 20 66 69 6e  rom start to fin
186d0 69 73 68 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ish..*/.void *sq
186e0 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
186f0 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61  te3*, void(*xTra
18700 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
18710 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
18720 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
18730 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
18740 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
18750 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
18760 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
18770 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
18780 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51  *.** CAPI3REF: Q
18790 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61  uery Progress Ca
187a0 6c 6c 62 61 63 6b 73 20 7b 46 31 32 39 31 30 7d  llbacks {F12910}
187b0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
187c0 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61  ine configures a
187d0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
187e0 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67  on - the.** prog
187f0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20  ress callback - 
18800 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
18810 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
18820 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e  ing long.** runn
18830 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ing calls to [sq
18840 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
18850 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
18860 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
18870 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41  get_table()].  A
18880 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
18890 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  r this.** interf
188a0 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
188b0 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
188c0 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
188d0 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  y..**.** If the 
188e0 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
188f0 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
18900 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ro, the operatio
18910 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
18920 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
18930 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
18940 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
18950 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
18960 20 6f 6e 20 61 20 47 55 49 20 64 69 61 6c 6f 67   on a GUI dialog
18970 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   box..**.** INVA
18980 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
18990 31 32 39 31 31 7d 20 54 68 65 20 63 61 6c 6c 62  12911} The callb
189a0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
189b0 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
189c0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
189d0 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20 20 20 20  ler().**        
189e0 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72    is invoked per
189f0 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
18a00 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
18a10 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  lls to.**       
18a20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70     [sqlite3_step
18a30 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ()]..**.** {F129
18a40 31 32 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73  12} The progress
18a50 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
18a60 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 76  oked once for ev
18a70 65 72 79 20 4e 20 76 69 72 74 75 61 6c 0a 2a 2a  ery N virtual.**
18a80 20 20 20 20 20 20 20 20 20 20 6d 61 63 68 69 6e            machin
18a90 65 20 6f 70 63 6f 64 65 73 2c 20 77 68 65 72 65  e opcodes, where
18aa0 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
18ab0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
18ac0 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71           the [sq
18ad0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
18ae0 61 6e 64 6c 65 72 28 29 5d 20 63 61 6c 6c 20 74  andler()] call t
18af0 68 61 74 20 72 65 67 69 73 74 65 72 65 64 0a 2a  hat registered.*
18b00 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63  *          the c
18b10 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 4e 20 69  allback.  If N i
18b20 73 20 6c 65 73 73 20 74 68 61 6e 20 31 2c 20 73  s less than 1, s
18b30 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
18b40 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20  handler().**    
18b50 20 20 20 20 20 20 61 63 74 73 20 61 73 20 69 66        acts as if
18b60 20 61 20 4e 55 4c 4c 20 70 72 6f 67 72 65 73 73   a NULL progress
18b70 20 68 61 6e 64 6c 65 72 20 68 61 64 20 62 65 65   handler had bee
18b80 6e 20 73 70 65 63 69 66 69 65 64 2e 0a 2a 2a 0a  n specified..**.
18b90 2a 2a 20 7b 46 31 32 39 31 33 7d 20 54 68 65 20  ** {F12913} The 
18ba0 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
18bb0 6b 20 69 74 73 65 6c 66 20 69 73 20 69 64 65 6e  k itself is iden
18bc0 74 69 66 69 65 64 20 62 79 20 74 68 65 20 74 68  tified by the th
18bd0 69 72 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ird.**          
18be0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
18bf0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
18c00 64 6c 65 72 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46  dler()..**.** {F
18c10 31 32 39 31 34 7d 20 54 68 65 20 66 6f 75 72 74  12914} The fourt
18c20 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
18c30 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
18c40 61 6e 64 6c 65 72 28 29 20 69 73 20 61 0a 2a 2a  andler() is a.**
18c50 2a 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 70  *         void p
18c60 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 74 6f  ointer passed to
18c70 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
18c80 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  llback.**       
18c90 20 20 20 66 75 6e 63 74 69 6f 6e 20 65 61 63 68     function each
18ca0 20 74 69 6d 65 20 69 74 20 69 73 20 69 6e 76 6f   time it is invo
18cb0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ked..**.** {F129
18cc0 31 35 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 6f  15} If a call to
18cd0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
18ce0 5d 20 72 65 73 75 6c 74 73 20 69 6e 20 66 65 77  ] results in few
18cf0 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  er than.**      
18d00 20 20 20 20 4e 20 6f 70 63 6f 64 65 73 20 62 65      N opcodes be
18d10 69 6e 67 20 65 78 65 63 75 74 65 64 2c 0a 2a 2a  ing executed,.**
18d20 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
18d30 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
18d40 62 61 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e  back is never in
18d50 76 6f 6b 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  voked. {END}.**.
18d60 2a 2a 20 7b 46 31 32 39 31 36 7d 20 45 76 65 72  ** {F12916} Ever
18d70 79 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  y call to [sqlit
18d80 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
18d90 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ler()].**       
18da0 20 20 20 6f 76 65 72 77 72 69 74 65 73 20 61 6e     overwrites an
18db0 79 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  y previously reg
18dc0 69 73 74 65 72 65 64 20 70 72 6f 67 72 65 73 73  istered progress
18dd0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
18de0 7b 46 31 32 39 31 37 7d 20 49 66 20 74 68 65 20  {F12917} If the 
18df0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
18e00 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
18e10 4c 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67 72 65  L then no progre
18e20 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68  ss.**          h
18e30 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65  andler is invoke
18e40 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 38  d..**.** {F12918
18e50 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73  } If the progres
18e60 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
18e70 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68 65  ns a result othe
18e80 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 0a 2a  r than 0, then.*
18e90 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62  *          the b
18ea0 65 68 61 76 69 6f 72 20 69 73 20 61 20 69 66 20  ehavior is a if 
18eb0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
18ec0 70 74 28 29 5d 20 68 61 64 20 62 65 65 6e 20 63  pt()] had been c
18ed0 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  alled..*/.void s
18ee0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
18ef0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
18f00 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
18f10 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
18f20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
18f30 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
18f40 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
18f50 20 7b 46 31 32 37 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F12700}.**.** 
18f60 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
18f70 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
18f80 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73  tabase file whos
18f90 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20  e name is given 
18fa0 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  by the.** filena
18fb0 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65  me argument. The
18fc0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
18fd0 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
18fe0 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
18ff0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
19000 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
19010 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
19020 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
19030 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
19040 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
19050 6e 31 36 28 29 2e 20 41 20 5b 64 61 74 61 62 61  n16(). A [databa
19060 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
19070 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
19080 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
19090 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
190a0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
190b0 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
190c0 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
190d0 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
190e0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
190f0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
19100 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
19110 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
19120 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
19130 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
19140 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
19150 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
19160 2a 20 6f 62 6a 65 63 74 2e 20 49 66 20 74 68 65  * object. If the
19170 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
19180 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
19190 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
191a0 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
191b0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
191c0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
191d0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
191e0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
191f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
19200 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
19210 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
19220 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
19230 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
19240 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
19250 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
19260 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a   of the error..*
19270 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  *.** The default
19280 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68   encoding for th
19290 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
192a0 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73  be UTF-8 if.** s
192b0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
192c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
192d0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64  () is called and
192e0 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68  .** UTF-16 in th
192f0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
19300 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f  der if sqlite3_o
19310 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e  pen16() is used.
19320 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
19330 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
19340 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
19350 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
19360 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
19370 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
19380 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
19390 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
193a0 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
193b0 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
193c0 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
193d0 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
193e0 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
193f0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
19400 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
19410 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
19420 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
19430 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
19440 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
19450 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
19460 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
19470 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
19480 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
19490 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
194a0 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
194b0 74 65 72 20 63 61 6e 20 62 65 20 6f 6e 65 20 6f  ter can be one o
194c0 66 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  f:.**.** <dl>.**
194d0 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45   <dt>[SQLITE_OPE
194e0 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e  N_READONLY]</dt>
194f0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
19500 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69  base is opened i
19510 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65  n read-only mode
19520 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61  .  If the databa
19530 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61  se does not.** a
19540 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e  lready exist, an
19550 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
19560 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
19570 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
19580 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a  READWRITE]</dt>.
19590 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
195a0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
195b0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
195c0 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c  iting if possibl
195d0 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a  e, or reading.**
195e0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c   only if the fil
195f0 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
19600 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
19610 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49  ating system.  I
19620 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65  n either.** case
19630 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75   the database mu
19640 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  st already exist
19650 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  , otherwise an e
19660 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
19670 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
19680 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
19690 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
196a0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
196b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
196c0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
196d0 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
196e0 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
196f0 69 73 20 63 72 65 61 74 65 73 20 69 74 20 69 66  is creates it if
19700 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
19710 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
19720 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
19730 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
19740 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
19750 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
19760 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
19770 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c  ().</dd>.** </dl
19780 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
19790 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
197a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
197b0 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
197c0 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
197d0 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
197e0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
197f0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
19800 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c  **.** If the fil
19810 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
19820 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
19830 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
19840 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
19850 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
19860 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
19870 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d  on.  This in-mem
19880 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
19890 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
198a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
198b0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
198c0 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
198d0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
198e0 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
198f0 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
19900 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
19910 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
19920 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
19930 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
19940 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
19950 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
19960 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
19970 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
19980 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
19990 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
199a0 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
199b0 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
199c0 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
199d0 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
199e0 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  uity..**.** If t
199f0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
19a00 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
19a10 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
19a20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
19a30 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
19a40 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
19a50 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
19a60 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
19a70 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
19a80 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
19a90 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
19aa0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
19ab0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  sed..**.** The f
19ac0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
19ad0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
19ae0 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
19af0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
19b00 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
19b10 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
19b20 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
19b30 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
19b40 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
19b50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
19b60 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20  should use.  If 
19b70 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
19b80 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
19b90 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
19ba0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
19bb0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
19bc0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
19bd0 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
19be0 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
19bf0 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
19c00 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
19c10 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
19c20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
19c30 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
19c40 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
19c50 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
19c60 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
19c70 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
19c80 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
19c90 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
19ca0 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
19cb0 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
19cc0 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
19cd0 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
19ce0 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
19cf0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
19d00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
19d10 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  )..**.** INVARIA
19d20 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  NTS:.**.** {F127
19d30 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
19d40 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
19d50 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
19d60 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
19d70 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
19d80 5d 20 69 6e 74 65 72 66 61 63 65 73 20 63 72 65  ] interfaces cre
19d90 61 74 65 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20  ate a new.**    
19da0 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
19db0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f  connection] asso
19dc0 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 20  ciated with.**  
19dd0 20 20 20 20 20 20 20 20 74 68 65 20 64 61 74 61          the data
19de0 62 61 73 65 20 66 69 6c 65 20 67 69 76 65 6e 20  base file given 
19df0 69 6e 20 74 68 65 69 72 20 66 69 72 73 74 20 70  in their first p
19e00 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
19e10 7b 46 31 32 37 30 32 7d 20 54 68 65 20 66 69 6c  {F12702} The fil
19e20 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
19e30 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
19e40 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20   UTF-8.**       
19e50 20 20 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f     for [sqlite3_
19e60 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  open()] and [sql
19e70 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
19e80 61 6e 64 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a  and as UTF-16.**
19e90 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 68 65            in the
19ea0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
19eb0 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f  er for [sqlite3_
19ec0 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  open16()]..**.**
19ed0 20 7b 46 31 32 37 30 33 7d 20 41 20 73 75 63 63   {F12703} A succ
19ee0 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
19ef0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  n of [sqlite3_op
19f00 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
19f10 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20  open16()],.**   
19f20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
19f30 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 72  e3_open_v2()] wr
19f40 69 74 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74  ites a pointer t
19f50 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20  o a new.**      
19f60 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
19f70 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 2a  nnection] into *
19f80 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ppDb..**.** {F12
19f90 37 30 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  704} The [sqlite
19fa0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
19fb0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61  te3_open16()], a
19fc0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
19fd0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
19fe0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  )] interfaces re
19ff0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
1a000 20 75 70 6f 6e 20 73 75 63 63 65 73 73 2c 0a 2a   upon success,.*
1a010 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 61 6e  *          or an
1a020 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
1a030 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69  ror code] on fai
1a040 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  lure..**.** {F12
1a050 37 30 36 7d 20 54 68 65 20 64 65 66 61 75 6c 74  706} The default
1a060 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66   text encoding f
1a070 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73  or a new databas
1a080 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  e created using.
1a090 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1a0a0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20  ite3_open()] or 
1a0b0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1a0c0 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ()] will be UTF-
1a0d0 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 37  8..**.** {F12707
1a0e0 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 74 65  } The default te
1a0f0 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  xt encoding for 
1a100 61 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  a new database c
1a110 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
1a120 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1a130 33 5f 6f 70 65 6e 31 36 28 29 5d 20 77 69 6c 6c  3_open16()] will
1a140 20 62 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a   be UTF-16..**.*
1a150 2a 20 7b 46 31 32 37 30 39 7d 20 54 68 65 20 5b  * {F12709} The [
1a160 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 46 2c 44  sqlite3_open(F,D
1a170 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  )] interface is 
1a180 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 0a 2a 2a  equivalent to.**
1a190 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1a1a0 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47  e3_open_v2(F,D,G
1a1b0 2c 30 29 5d 20 77 68 65 72 65 20 74 68 65 20 47  ,0)] where the G
1a1c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
1a1d0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
1a1e0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1a1f0 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ]|[SQLITE_OPEN_C
1a200 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  REATE]..**.** {F
1a210 31 32 37 31 31 7d 20 49 66 20 74 68 65 20 47 20  12711} If the G 
1a220 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
1a230 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c  lite3_open_v2(F,
1a240 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73  D,G,V)] contains
1a250 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1a260 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49   bit value [SQLI
1a270 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
1a280 5d 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  ] then the datab
1a290 61 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a  ase is opened.**
1a2a0 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 72 65            for re
1a2b0 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ading only..**.*
1a2c0 2a 20 7b 46 31 32 37 31 32 7d 20 49 66 20 74 68  * {F12712} If th
1a2d0 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e G parameter to
1a2e0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1a2f0 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74  2(F,D,G,V)] cont
1a300 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ains the.**     
1a310 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b       bit value [
1a320 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1a330 57 52 49 54 45 5d 20 74 68 65 6e 20 74 68 65 20  WRITE] then the 
1a340 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1a350 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ed.**          r
1a360 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
1a370 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
1a380 6f 72 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f  or for reading o
1a390 6e 6c 79 20 69 66 20 74 68 65 0a 2a 2a 20 20 20  nly if the.**   
1a3a0 20 20 20 20 20 20 20 66 69 6c 65 20 69 73 20 77         file is w
1a3b0 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
1a3c0 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
1a3d0 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  system..**.** {F
1a3e0 31 32 37 31 33 7d 20 49 66 20 74 68 65 20 47 20  12713} If the G 
1a3f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
1a400 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32 28 46 2c  lite3_open(v2(F,
1a410 44 2c 47 2c 56 29 5d 20 6f 6d 69 74 73 20 74 68  D,G,V)] omits th
1a420 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69  e.**          bi
1a430 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  t value [SQLITE_
1a440 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64  OPEN_CREATE] and
1a450 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
1a460 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20  es not.**       
1a470 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78     previously ex
1a480 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
1a490 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
1a4a0 20 7b 46 31 32 37 31 34 7d 20 49 66 20 74 68 65   {F12714} If the
1a4b0 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   G parameter to 
1a4c0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32  [sqlite3_open(v2
1a4d0 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61  (F,D,G,V)] conta
1a4e0 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ins the.**      
1a4f0 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53      bit value [S
1a500 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1a510 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  E] and the datab
1a520 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
1a530 20 20 20 20 20 20 20 20 20 70 72 65 76 69 6f 75           previou
1a540 73 6c 79 20 65 78 69 73 74 2c 20 74 68 65 6e 20  sly exist, then 
1a550 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
1a560 64 65 20 74 6f 20 63 72 65 61 74 65 20 61 6e 64  de to create and
1a570 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 69  .**          ini
1a580 74 69 61 6c 69 7a 65 20 74 68 65 20 64 61 74 61  tialize the data
1a590 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  base..**.** {F12
1a5a0 37 31 37 7d 20 49 66 20 74 68 65 20 66 69 6c 65  717} If the file
1a5b0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 74 6f  name argument to
1a5c0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1a5d0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
1a5e0 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  16()],.**       
1a5f0 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f     or [sqlite3_o
1a600 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 22 3a 6d  pen_v2()] is ":m
1a610 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e  emory:", then an
1a620 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20   private,.**    
1a630 20 20 20 20 20 20 65 70 68 65 6d 65 72 61 6c 2c        ephemeral,
1a640 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1a650 61 73 65 20 69 73 20 63 72 65 61 74 65 64 20 66  ase is created f
1a660 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
1a670 6e 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c  n..**          <
1a680 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f  todo>Is SQLITE_O
1a690 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54  PEN_CREATE|SQLIT
1a6a0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1a6b0 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20   required.**    
1a6c0 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33        in sqlite3
1a6d0 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64  _open_v2()?</tod
1a6e0 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 39  o>.**.** {F12719
1a6f0 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d  } If the filenam
1a700 65 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20  e is NULL or an 
1a710 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
1a720 65 6e 20 61 20 70 72 69 76 61 74 65 2c 0a 2a 2a  en a private,.**
1a730 20 20 20 20 20 20 20 20 20 20 65 70 68 65 6d 65            epheme
1a740 72 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  ral on-disk data
1a750 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
1a760 61 74 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20  ated..**        
1a770 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54    <todo>Is SQLIT
1a780 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51  E_OPEN_CREATE|SQ
1a790 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1a7a0 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20  ITE required.** 
1a7b0 20 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69           in sqli
1a7c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f  te3_open_v2()?</
1a7d0 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  todo>.**.** {F12
1a7e0 37 32 31 7d 20 54 68 65 20 5b 64 61 74 61 62 61  721} The [databa
1a7f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63  se connection] c
1a800 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74  reated by [sqlit
1a810 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47  e3_open_v2(F,D,G
1a820 2c 56 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,V)].**         
1a830 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 5b 73   will use the [s
1a840 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1a850 63 74 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  ct identified by
1a860 20 74 68 65 20 56 20 70 61 72 61 6d 65 74 65 72   the V parameter
1a870 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
1a880 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1a890 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1a8a0 74 20 69 66 20 56 20 69 73 20 61 20 4e 55 4c 4c  t if V is a NULL
1a8b0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1a8c0 7b 46 31 32 37 32 33 7d 20 54 77 6f 20 5b 64 61  {F12723} Two [da
1a8d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a8e0 6e 73 5d 20 77 69 6c 6c 20 73 68 61 72 65 20 61  ns] will share a
1a8f0 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 20 69 66   common cache if
1a900 20 62 6f 74 68 20 77 65 72 65 0a 2a 2a 20 20 20   both were.**   
1a910 20 20 20 20 20 20 20 6f 70 65 6e 65 64 20 77 69         opened wi
1a920 74 68 20 74 68 65 20 73 61 6d 65 20 56 46 53 20  th the same VFS 
1a930 77 68 69 6c 65 20 5b 73 68 61 72 65 64 20 63 61  while [shared ca
1a940 63 68 65 20 6d 6f 64 65 5d 20 77 61 73 20 65 6e  che mode] was en
1a950 61 62 6c 65 64 20 61 6e 64 0a 2a 2a 20 20 20 20  abled and.**    
1a960 20 20 20 20 20 20 69 66 20 62 6f 74 68 20 66 69        if both fi
1a970 6c 65 6e 61 6d 65 73 20 63 6f 6d 70 61 72 65 20  lenames compare 
1a980 65 71 75 61 6c 20 75 73 69 6e 67 20 6d 65 6d 63  equal using memc
1a990 6d 70 28 29 20 61 66 74 65 72 20 68 61 76 69 6e  mp() after havin
1a9a0 67 20 62 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20  g been.**       
1a9b0 20 20 20 70 72 6f 63 65 73 73 65 64 20 62 79 20     processed by 
1a9c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
1a9d0 20 7c 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   | xFullPathname
1a9e0 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  ] method of the 
1a9f0 56 46 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  VFS..*/.int sqli
1aa00 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
1aa10 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
1aa20 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1aa30 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
1aa40 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1aa50 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
1aa60 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1aa70 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
1aa80 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1aa90 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
1aaa0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
1aab0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1aac0 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
1aad0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
1aae0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1aaf0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1ab00 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1ab10 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
1ab20 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
1ab30 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1ab40 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
1ab50 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1ab60 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
1ab70 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1ab80 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
1ab90 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
1aba0 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
1abb0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
1abc0 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
1abd0 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
1abe0 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
1abf0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
1ac00 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
1ac10 73 73 61 67 65 73 20 7b 46 31 32 38 30 30 7d 0a  ssages {F12800}.
1ac20 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1ac30 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
1ac40 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
1ac50 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
1ac60 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
1ac70 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1ac80 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
1ac90 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
1aca0 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
1acb0 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
1acc0 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
1acd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
1ace0 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
1acf0 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
1ad00 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1ad10 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
1ad20 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
1ad30 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
1ad40 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
1ad50 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
1ad60 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1ad70 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c  errmsg() and sql
1ad80 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20  ite3_errmsg16() 
1ad90 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
1ada0 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20  anguage.** text 
1adb0 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
1adc0 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74  he error, as eit
1add0 68 65 72 20 55 54 46 38 20 6f 72 20 55 54 46 31  her UTF8 or UTF1
1ade0 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
1adf0 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** Memory to hol
1ae00 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
1ae10 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
1ae20 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
1ae30 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
1ae40 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
1ae50 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75  ed to worry abou
1ae60 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  t freeing the re
1ae70 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
1ae80 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
1ae90 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
1aea0 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
1aeb0 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
1aec0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
1aed0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
1aee0 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
1aef0 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  s..**.** INVARIA
1af00 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38  NTS:.**.** {F128
1af10 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
1af20 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69 6e 74  _errcode(D)] int
1af30 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
1af40 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20 20  he numeric.**   
1af50 20 20 20 20 20 20 20 5b 72 65 73 75 6c 74 20 63         [result c
1af60 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  ode] or [extende
1af70 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
1af80 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
1af90 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ntly.**         
1afa0 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63   failed interfac
1afb0 65 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  e call associate
1afc0 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
1afd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1afe0 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30   D..**.** {F1280
1aff0 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
1b000 65 72 72 6d 73 67 28 44 29 5d 20 61 6e 64 20 5b  errmsg(D)] and [
1b010 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1b020 28 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  (D)].**         
1b030 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75   interfaces retu
1b040 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
1b050 61 67 65 20 74 65 78 74 20 74 68 61 74 20 64 65  age text that de
1b060 73 63 72 69 62 65 73 0a 2a 2a 20 20 20 20 20 20  scribes.**      
1b070 20 20 20 20 74 68 65 20 65 72 72 6f 72 20 69 6e      the error in
1b080 20 74 68 65 20 6d 6f 73 74 6c 79 20 72 65 63 65   the mostly rece
1b090 6e 74 6c 79 20 66 61 69 6c 65 64 20 69 6e 74 65  ntly failed inte
1b0a0 72 66 61 63 65 20 63 61 6c 6c 2c 0a 2a 2a 20 20  rface call,.**  
1b0b0 20 20 20 20 20 20 20 20 65 6e 63 6f 64 65 64 20          encoded 
1b0c0 61 73 20 65 69 74 68 65 72 20 55 54 46 38 20 6f  as either UTF8 o
1b0d0 72 20 55 54 46 31 36 20 72 65 73 70 65 63 74 69  r UTF16 respecti
1b0e0 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  vely..**.** {F12
1b0f0 38 30 37 7d 20 54 68 65 20 73 74 72 69 6e 67 73  807} The strings
1b100 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1b110 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
1b120 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
1b130 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20  msg16()].**     
1b140 20 20 20 20 20 61 72 65 20 76 61 6c 69 64 20 75       are valid u
1b150 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 53 51  ntil the next SQ
1b160 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 63  Lite interface c
1b170 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38  all..**.** {F128
1b180 30 38 7d 20 43 61 6c 6c 73 20 74 6f 20 41 50 49  08} Calls to API
1b190 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 64   routines that d
1b1a0 6f 20 6e 6f 74 20 72 65 74 75 72 6e 20 61 6e 20  o not return an 
1b1b0 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20  error code.**   
1b1c0 20 20 20 20 20 20 20 28 65 78 61 6d 70 6c 65 3a         (example:
1b1d0 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
1b1e0 6f 75 6e 74 28 29 5d 29 20 64 6f 20 6e 6f 74 0a  ount()]) do not.
1b1f0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 68 61 6e  **          chan
1b200 67 65 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ge the error cod
1b210 65 20 6f 72 20 6d 65 73 73 61 67 65 20 72 65 74  e or message ret
1b220 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  urned by.**     
1b230 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72       [sqlite3_er
1b240 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74  rcode()], [sqlit
1b250 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72  e3_errmsg()], or
1b260 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1b270 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  16()]..**.** {F1
1b280 32 38 30 39 7d 20 49 6e 74 65 72 66 61 63 65 73  2809} Interfaces
1b290 20 74 68 61 74 20 61 72 65 20 6e 6f 74 20 61 73   that are not as
1b2a0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
1b2b0 73 70 65 63 69 66 69 63 0a 2a 2a 20 20 20 20 20  specific.**     
1b2c0 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
1b2d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 65 78 61 6d  onnection] (exam
1b2e0 70 6c 65 73 3a 0a 2a 2a 20 20 20 20 20 20 20 20  ples:.**        
1b2f0 20 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e    [sqlite3_mprin
1b300 74 66 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  tf()] or [sqlite
1b310 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
1b320 63 61 63 68 65 28 29 5d 0a 2a 2a 20 20 20 20 20  cache()].**     
1b330 20 20 20 20 20 64 6f 20 6e 6f 74 20 63 68 61 6e       do not chan
1b340 67 65 20 74 68 65 20 76 61 6c 75 65 73 20 72 65  ge the values re
1b350 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20  turned by.**    
1b360 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
1b370 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69  rrcode()], [sqli
1b380 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f  te3_errmsg()], o
1b390 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
1b3a0 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  g16()]..*/.int s
1b3b0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73  qlite3_errcode(s
1b3c0 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e  qlite3 *db);.con
1b3d0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1b3e0 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a  _errmsg(sqlite3*
1b3f0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
1b400 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1b410 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1b420 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
1b430 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
1b440 20 7b 46 31 33 30 30 30 7d 0a 2a 2a 20 4b 45 59   {F13000}.** KEY
1b450 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
1b460 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
1b470 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
1b480 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
1b490 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
1b4a0 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
1b4b0 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
1b4c0 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ment..** This ob
1b4d0 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c  ject is variousl
1b4e0 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72  y known as a "pr
1b4f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1b500 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69  " or a.** "compi
1b510 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
1b520 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20  t" or simply as 
1b530 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a  a "statement"..*
1b540 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66  *.** The life of
1b550 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a   a statement obj
1b560 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69  ect goes somethi
1b570 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ng like this:.**
1b580 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
1b590 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65   Create the obje
1b5a0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
1b5b0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1b5c0 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  or a related.** 
1b5d0 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a       function..*
1b5e0 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
1b5f0 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61  es to [host para
1b600 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
1b610 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1b620 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
1b630 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
1b640 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
1b650 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
1b660 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
1b670 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
1b680 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74  > Reset the stat
1b690 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
1b6a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
1b6b0 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
1b6c0 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
1b6d0 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
1b6e0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
1b6f0 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
1b700 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
1b710 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1b720 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
1b730 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65   Refer to docume
1b740 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  ntation on indiv
1b750 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62  idual methods ab
1b760 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ove for addition
1b770 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1b780 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
1b790 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
1b7a0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
1b7b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b7c0 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
1b7d0 20 7b 46 31 32 37 36 30 7d 0a 2a 2a 0a 2a 2a 20   {F12760}.**.** 
1b7e0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
1b7f0 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f  llows the size o
1b800 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72  f various constr
1b810 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74  ucts to be limit
1b820 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65  ed.** on a conne
1b830 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74  ction by connect
1b840 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20  ion basis.  The 
1b850 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1b860 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  is the.** [datab
1b870 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1b880 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74  whose limit is t
1b890 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72  o be set or quer
1b8a0 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ied.  The.** sec
1b8b0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
1b8c0 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d   one of the [lim
1b8d0 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74  it categories] t
1b8e0 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20  hat define a.** 
1b8f0 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75  class of constru
1b900 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c  cts to be size l
1b910 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69  imited.  The thi
1b920 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
1b930 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74  the.** new limit
1b940 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72   for that constr
1b950 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69  uct.  The functi
1b960 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f  on returns the o
1b970 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20  ld limit..**.** 
1b980 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
1b990 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
1b9a0 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
1b9b0 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
1b9c0 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20  * For the limit 
1b9d0 63 61 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49  category of SQLI
1b9e0 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65  TE_LIMIT_XYZ the
1b9f0 72 65 20 69 73 20 61 20 68 61 72 64 20 75 70 70  re is a hard upp
1ba00 65 72 0a 2a 2a 20 62 6f 75 6e 64 20 73 65 74 20  er.** bound set 
1ba10 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  by a compile-tim
1ba20 65 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  e C preprocessor
1ba30 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 53 51 4c   macro named SQL
1ba40 49 54 45 5f 4d 41 58 5f 58 59 5a 2e 0a 2a 2a 20  ITE_MAX_XYZ..** 
1ba50 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
1ba60 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
1ba70 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
1ba80 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20 74  .).** Attempts t
1ba90 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
1baa0 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
1bab0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
1bac0 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
1bad0 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
1bae0 61 72 64 20 75 70 70 65 72 20 6c 69 6d 69 74 2e  ard upper limit.
1baf0 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20  .**.** Run time 
1bb00 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e  limits are inten
1bb10 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61  ded for use in a
1bb20 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
1bb30 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20   manage.** both 
1bb40 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e  their own intern
1bb50 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  al database and 
1bb60 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74  also databases t
1bb70 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c  hat are controll
1bb80 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74  ed.** by untrust
1bb90 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  ed external sour
1bba0 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ces.  An example
1bbb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67   application mig
1bbc0 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 62 72  ht be a.** webbr
1bbd0 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
1bbe0 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
1bbf0 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
1bc00 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
1bc10 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
1bc20 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
1bc30 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
1bc40 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
1bc50 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
1bc60 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
1bc70 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
1bc80 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
1bc90 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
1bca0 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
1bcb0 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
1bcc0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
1bcd0 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
1bce0 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
1bcf0 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
1bd00 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
1bd10 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
1bd20 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
1bd30 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
1bd40 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
1bd50 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1bd60 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
1bd70 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
1bd80 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
1bd90 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
1bda0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1bdb0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
1bdc0 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
1bdd0 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
1bde0 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
1bdf0 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
1be00 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
1be10 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
1be20 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f   is currently co
1be30 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d  nsidered experim
1be40 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62  ental and is sub
1be50 6a 65 63 74 0a 2a 2a 20 74 6f 20 63 68 61 6e 67  ject.** to chang
1be60 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 77 69 74  e or removal wit
1be70 68 6f 75 74 20 70 72 69 6f 72 20 6e 6f 74 69 63  hout prior notic
1be80 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
1be90 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37  NTS:.**.** {F127
1bea0 36 32 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  62} A successful
1beb0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1bec0 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20  3_limit(D,C,V)] 
1bed0 77 68 65 72 65 20 56 20 69 73 0a 2a 2a 20 20 20  where V is.**   
1bee0 20 20 20 20 20 20 20 70 6f 73 69 74 69 76 65 20         positive 
1bef0 63 68 61 6e 67 65 73 20 74 68 65 20 6c 69 6d 69  changes the limi
1bf00 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  t on the size of
1bf10 20 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 20   construct C in 
1bf20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1bf30 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1bf40 74 69 6f 6e 5d 20 44 20 74 6f 20 74 68 65 20 6c  tion] D to the l
1bf50 65 73 73 65 72 20 6f 66 20 56 20 61 6e 64 20 74  esser of V and t
1bf60 68 65 20 68 61 72 64 20 75 70 70 65 72 0a 2a 2a  he hard upper.**
1bf70 20 20 20 20 20 20 20 20 20 20 62 6f 75 6e 64 20            bound 
1bf80 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 43  on the size of C
1bf90 20 74 68 61 74 20 69 73 20 73 65 74 20 61 74 20   that is set at 
1bfa0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 0a 2a 2a  compile-time..**
1bfb0 0a 2a 2a 20 7b 46 31 32 37 36 36 7d 20 41 20 73  .** {F12766} A s
1bfc0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
1bfd0 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  o [sqlite3_limit
1bfe0 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56  (D,C,V)] where V
1bff0 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20   is negative.** 
1c000 20 20 20 20 20 20 20 20 20 6c 65 61 76 65 73 20           leaves 
1c010 74 68 65 20 73 74 61 74 65 20 6f 66 20 74 68 65  the state of the
1c020 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c030 63 74 69 6f 6e 5d 20 44 20 75 6e 63 68 61 6e 67  ction] D unchang
1c040 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 36  ed..**.** {F1276
1c050 39 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  9} A successful 
1c060 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1c070 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 72  _limit(D,C,V)] r
1c080 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20  eturns the.**   
1c090 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
1c0a0 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65  the limit on the
1c0b0 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75   size of constru
1c0c0 63 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20 20  ct C in the.**  
1c0d0 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
1c0e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
1c0f0 61 73 20 69 74 20 77 61 73 20 70 72 69 6f 72 20  as it was prior 
1c100 74 6f 20 74 68 65 20 63 61 6c 6c 2e 0a 2a 2f 0a  to the call..*/.
1c110 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69  int sqlite3_limi
1c120 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
1c130 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b  id, int newVal);
1c140 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c150 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74  : Run-Time Limit
1c160 20 43 61 74 65 67 6f 72 69 65 73 20 7b 46 31 32   Categories {F12
1c170 37 39 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  790}.** KEYWORDS
1c180 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  : {limit categor
1c190 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  y} {limit catego
1c1a0 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
1c1b0 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
1c1c0 6e 65 20 76 61 72 69 6f 75 73 20 61 73 70 65 63  ne various aspec
1c1d0 74 73 20 6f 66 20 61 20 5b 64 61 74 61 62 61 73  ts of a [databas
1c1e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
1c1f0 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 69 6d   that can be lim
1c200 69 74 65 64 20 69 6e 20 73 69 7a 65 20 62 79 20  ited in size by 
1c210 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1c220 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
1c230 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
1c240 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
1c250 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73  s are as follows
1c260 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  :.**.** <dl>.** 
1c270 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1c280 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1c290 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1c2a0 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69  size of any stri
1c2b0 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61  ng or BLOB or ta
1c2c0 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a  ble row.<dd>.**.
1c2d0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1c2e0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
1c2f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1c300 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1c310 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1c320 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
1c330 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
1c340 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OLUMN</dt>.** <d
1c350 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1c360 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
1c370 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e  in a table defin
1c380 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a  ition or in the.
1c390 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ** result set of
1c3a0 20 61 20 53 45 4c 45 43 54 20 6f 72 20 74 68 65   a SELECT or the
1c3b0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1c3c0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
1c3d0 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
1c3e0 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
1c3f0 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
1c400 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1c410 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
1c420 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
1c430 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
1c440 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
1c450 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
1c460 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  pression.</dd>.*
1c470 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1c480 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
1c490 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ELECT</dt>.** <d
1c4a0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1c4b0 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
1c4c0 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45   a compound SELE
1c4d0 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  CT statement.</d
1c4e0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
1c4f0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
1c500 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
1c510 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1c520 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
1c530 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
1c540 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
1c550 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1c560 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
1c570 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ent.</dd>.**.** 
1c580 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1c590 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
1c5a0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1c5b0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1c5c0 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
1c5d0 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a  unction.</dd>.**
1c5e0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
1c5f0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64  IMIT_ATTACHED</d
1c600 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1c610 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1c620 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
1c630 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  es.</dd>.**.** <
1c640 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1c650 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
1c660 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
1c670 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
1c680 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
1c690 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
1c6a0 65 20 4c 49 4b 45 20 6f 72 0a 2a 2a 20 47 4c 4f  e LIKE or.** GLO
1c6b0 42 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64  B operators.</dd
1c6c0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1c6d0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
1c6e0 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
1c6f0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1c700 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72 69 61   number of varia
1c710 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c 20 73  bles in an SQL s
1c720 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 63 61  tatement that ca
1c730 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f  n.** be bound.</
1c740 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  dd>.** </dl>.*/.
1c750 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1c760 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
1c770 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
1c780 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c790 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
1c7a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c7b0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
1c7c0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
1c7d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c7e0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
1c7f0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
1c800 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
1c810 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
1c820 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
1c830 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
1c840 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
1c850 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
1c860 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
1c870 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
1c880 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
1c890 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
1c8a0 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
1c8b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
1c8c0 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
1c8d0 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
1c8e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
1c8f0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
1c900 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
1c910 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
1c920 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
1c930 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a          9../*.**
1c940 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
1c950 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74  ling An SQL Stat
1c960 65 6d 65 6e 74 20 7b 46 31 33 30 31 30 7d 0a 2a  ement {F13010}.*
1c970 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
1c980 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
1c990 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  ler}.**.** To ex
1c9a0 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
1c9b0 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
1c9c0 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
1c9d0 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
1c9e0 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
1c9f0 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
1ca00 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
1ca10 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c   first argument,
1ca20 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74   "db", is a [dat
1ca30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ca40 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  ] obtained from 
1ca50 61 0a 2a 2a 20 70 72 69 6f 72 20 63 61 6c 6c 20  a.** prior call 
1ca60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
1ca70 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1ca80 65 6e 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  en_v2()] or [sql
1ca90 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
1caa0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
1cab0 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
1cac0 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
1cad0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
1cae0 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
1caf0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
1cb00 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
1cb10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1cb20 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1cb30 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
1cb40 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
1cb50 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
1cb60 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
1cb70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1cb80 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
1cb90 2d 31 36 2e 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  -16.{END}.**.** 
1cba0 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
1cbb0 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68  ument is less th
1cbc0 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53  an zero, then zS
1cbd0 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
1cbe0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65   the.** first ze
1cbf0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 49  ro terminator. I
1cc00 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  f nByte is non-n
1cc10 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
1cc20 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a   is the maximum.
1cc30 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79  ** number of  by
1cc40 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53  tes read from zS
1cc50 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20  ql.  When nByte 
1cc60 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
1cc70 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72   the.** zSql str
1cc80 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68  ing ends at eith
1cc90 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30  er the first '\0
1cca0 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20  00' or '\u0000' 
1ccb0 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20  character or.** 
1ccc0 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74  the nByte-th byt
1ccd0 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  e, whichever com
1cce0 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65  es first. If the
1ccf0 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a   caller knows.**
1cd00 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
1cd10 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
1cd20 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
1cd30 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  n there is a sma
1cd40 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63  ll.** performanc
1cd50 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62  e advantage to b
1cd60 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73  e gained by pass
1cd70 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72  ing an nByte par
1cd80 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ameter that.** i
1cd90 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e  s equal to the n
1cda0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
1cdb0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
1cdc0 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c  ng <i>including<
1cdd0 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  /i>.** the nul-t
1cde0 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e  erminator bytes.
1cdf0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54  {END}.**.** *pzT
1ce00 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
1ce10 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
1ce20 74 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20  t byte past the 
1ce30 65 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  end of the.** fi
1ce40 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
1ce50 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73  t in zSql.  Thes
1ce60 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 20  e routines only 
1ce70 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
1ce80 74 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  t.** statement i
1ce90 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61  n zSql, so *pzTa
1cea0 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  il is left point
1ceb0 69 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d 61  ing to what rema
1cec0 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65  ins.** uncompile
1ced0 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74  d..**.** *ppStmt
1cee0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
1cef0 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
1cf00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1cf10 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
1cf20 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
1cf30 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
1cf40 28 29 5d 2e 20 20 49 66 20 74 68 65 72 65 20 69  ()].  If there i
1cf50 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
1cf60 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
1cf70 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69   NULL.  If the i
1cf80 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
1cf90 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
1cfa0 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
1cfb0 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
1cfc0 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
1cfd0 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
1cfe0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 55 31 33  to NULL..** {U13
1cff0 30 31 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67  018} The calling
1d000 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
1d010 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
1d020 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
1d030 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
1d040 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
1d050 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
1d060 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
1d070 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
1d080 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c  *.** On success,
1d090 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20   [SQLITE_OK] is 
1d0a0 72 65 74 75 72 6e 65 64 2c 20 6f 74 68 65 72 77  returned, otherw
1d0b0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
1d0c0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
1d0d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1d0e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
1d0f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1d100 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
1d110 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
1d120 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
1d130 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
1d140 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
1d150 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
1d160 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
1d170 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1d180 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
1d190 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
1d1a0 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 32  d..** In the "v2
1d1b0 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
1d1c0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
1d1d0 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
1d1e0 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
1d1f0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
1d200 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
1d210 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
1d220 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
1d230 2e 20 7b 45 4e 44 7d 20 54 68 69 73 20 63 61 75  . {END} This cau
1d240 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
1d250 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
1d260 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
1d270 61 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  a differently in
1d280 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a   two ways:.**.**
1d290 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
1d2a0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
1d2b0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
1d2c0 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
1d2d0 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
1d2e0 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
1d2f0 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
1d300 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1d310 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
1d320 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
1d330 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
1d340 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
1d350 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49  run it again.  I
1d360 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 73  f the schema has
1d370 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61   changed in.** a
1d380 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20   way that makes 
1d390 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f  the statement no
1d3a0 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b   longer valid, [
1d3b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1d3c0 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65  will still.** re
1d3d0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48  turn [SQLITE_SCH
1d3e0 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b  EMA].  But unlik
1d3f0 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
1d400 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53  avior, [SQLITE_S
1d410 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77  CHEMA] is.** now
1d420 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20   a fatal error. 
1d430 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   Calling [sqlite
1d440 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1d450 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d  again will not m
1d460 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  ake the.** error
1d470 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a   go away.  Note:
1d480 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72   use [sqlite3_er
1d490 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20  rmsg()] to find 
1d4a0 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74  the text.** of t
1d4b0 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72  he parsing error
1d4c0 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e   that results in
1d4d0 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45   an [SQLITE_SCHE
1d4e0 4d 41 5d 20 72 65 74 75 72 6e 2e 20 7b 45 4e 44  MA] return. {END
1d4f0 7d 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  }.** </li>.**.**
1d500 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e   <li>.** When an
1d510 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b   error occurs, [
1d520 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1d530 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
1d540 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a  of the detailed.
1d550 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
1d560 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
1d570 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 54 68 65  ror codes].  The
1d580 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
1d590 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
1d5a0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
1d5b0 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
1d5c0 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
1d5d0 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
1d5e0 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 79 6f 75 20  code.** and you 
1d5f0 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
1d600 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
1d610 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
1d620 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 0a 2a  et()] in order.*
1d630 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  * to find the un
1d640 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
1d650 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
1d660 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
1d670 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
1d680 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
1d690 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
1d6a0 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
1d6b0 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
1d6c0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
1d6d0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  l>.**.** INVARIA
1d6e0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30  NTS:.**.** {F130
1d6f0 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  11} The [sqlite3
1d700 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71 6c  _prepare(db,zSql
1d710 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  ,...)] and.**   
1d720 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1d730 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53  prepare_v2(db,zS
1d740 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  ql,...)] interfa
1d750 63 65 73 20 69 6e 74 65 72 70 72 65 74 20 74 68  ces interpret th
1d760 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65  e.**          te
1d770 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71 6c  xt in their zSql
1d780 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 55 54   parameter as UT
1d790 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30  F-8..**.** {F130
1d7a0 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  12} The [sqlite3
1d7b0 5f 70 72 65 70 61 72 65 31 36 28 64 62 2c 7a 53  _prepare16(db,zS
1d7c0 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20  ql,...)] and.** 
1d7d0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1d7e0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 64  3_prepare16_v2(d
1d7f0 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74  b,zSql,...)] int
1d800 65 72 66 61 63 65 73 20 69 6e 74 65 72 70 72 65  erfaces interpre
1d810 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  t the.**        
1d820 20 20 74 65 78 74 20 69 6e 20 74 68 65 69 72 20    text in their 
1d830 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61  zSql parameter a
1d840 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
1d850 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1d860 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 33  r..**.** {F13013
1d870 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61  } If the nByte a
1d880 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
1d890 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64  te3_prepare_v2(d
1d8a0 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e  b,zSql,nByte,...
1d8b0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  )].**          a
1d8c0 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  nd its variants 
1d8d0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  is less than zer
1d8e0 6f 2c 20 74 68 65 20 53 51 4c 20 74 65 78 74 20  o, the SQL text 
1d8f0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  is.**          r
1d900 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 20 69 73  ead from zSql is
1d910 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 20   read up to the 
1d920 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
1d930 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  nator..**.** {F1
1d940 33 30 31 34 7d 20 49 66 20 74 68 65 20 6e 42 79  3014} If the nBy
1d950 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  te argument to [
1d960 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1d970 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65  v2(db,zSql,nByte
1d980 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
1d990 20 20 20 61 6e 64 20 69 74 73 20 76 61 72 69 61     and its varia
1d9a0 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  nts is non-negat
1d9b0 69 76 65 2c 20 74 68 65 6e 20 61 74 20 6d 6f 73  ive, then at mos
1d9c0 74 20 6e 42 79 74 65 73 20 62 79 74 65 73 20 6f  t nBytes bytes o
1d9d0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  f.**          SQ
1d9e0 4c 20 74 65 78 74 20 69 73 20 72 65 61 64 20 66  L text is read f
1d9f0 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20  rom zSql..**.** 
1da00 7b 46 31 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c  {F13015} In [sql
1da10 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1da20 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61  db,zSql,N,P,pzTa
1da30 69 6c 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  il)] and its var
1da40 69 61 6e 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  iants.**        
1da50 20 20 69 66 20 74 68 65 20 7a 53 71 6c 20 69 6e    if the zSql in
1da60 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
1da70 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
1da80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
1da90 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 70 7a            and pz
1daa0 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
1dab0 2c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  , then *pzTail i
1dac0 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
1dad0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
1dae0 20 20 20 66 69 72 73 74 20 62 79 74 65 20 70 61     first byte pa
1daf0 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
1db00 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
1db10 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a  ement in zSql..*
1db20 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f  *          <todo
1db30 3e 57 68 61 74 20 64 6f 65 73 20 2a 70 7a 54 61  >What does *pzTa
1db40 69 6c 20 70 6f 69 6e 74 20 74 6f 20 69 66 20 74  il point to if t
1db50 68 65 72 65 20 69 73 20 6f 6e 65 20 73 74 61 74  here is one stat
1db60 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a  ement?</todo>.**
1db70 0a 2a 2a 20 7b 46 31 33 30 31 36 7d 20 41 20 73  .** {F13016} A s
1db80 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
1db90 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
1dba0 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c  re_v2(db,zSql,N,
1dbb0 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20  ppStmt,...)].** 
1dbc0 20 20 20 20 20 20 20 20 20 6f 72 20 6f 6e 65 20           or one 
1dbd0 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  of its variants 
1dbe0 77 72 69 74 65 73 20 69 6e 74 6f 20 2a 70 70 53  writes into *ppS
1dbf0 74 6d 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  tmt a pointer to
1dc00 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20   a new.**       
1dc10 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
1dc20 74 65 6d 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69  tement] or a poi
1dc30 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 69 66 20  nter to NULL if 
1dc40 7a 53 71 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  zSql contains.**
1dc50 20 20 20 20 20 20 20 20 20 20 6e 6f 74 68 69 6e            nothin
1dc60 67 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69  g other than whi
1dc70 74 65 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65  tespace or comme
1dc80 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30  nts..**.** {F130
1dc90 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  19} The [sqlite3
1dca0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
1dcb0 6e 74 65 72 66 61 63 65 20 61 6e 64 20 69 74 73  nterface and its
1dcc0 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e   variants return
1dcd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
1dce0 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61  LITE_OK] or an a
1dcf0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
1dd00 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66 61 69  r code] upon fai
1dd10 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  lure..**.** {F13
1dd20 30 32 31 7d 20 42 65 66 6f 72 65 20 5b 73 71 6c  021} Before [sql
1dd30 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c  ite3_prepare(db,
1dd40 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70 53 74 6d  zSql,nByte,ppStm
1dd50 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 20 69 74  t,pzTail)] or it
1dd60 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  s.**          va
1dd70 72 69 61 6e 74 73 20 72 65 74 75 72 6e 73 20 61  riants returns a
1dd80 6e 20 65 72 72 6f 72 20 28 61 6e 79 20 76 61 6c  n error (any val
1dd90 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
1dda0 51 4c 49 54 45 5f 4f 4b 5d 29 2c 0a 2a 2a 20 20  QLITE_OK]),.**  
1ddb0 20 20 20 20 20 20 20 20 74 68 65 79 20 66 69 72          they fir
1ddc0 73 74 20 73 65 74 20 2a 70 70 53 74 6d 74 20 74  st set *ppStmt t
1ddd0 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
1dde0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
1ddf0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1de00 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1de10 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1de20 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1de30 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1de40 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1de50 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
1de60 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
1de70 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
1de80 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
1de90 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
1dea0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
1deb0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
1dec0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
1ded0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1dee0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1def0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1df00 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1df10 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
1df20 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1df30 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
1df40 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1df50 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
1df60 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1df70 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
1df80 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
1df90 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
1dfa0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1dfb0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1dfc0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1dfd0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1dfe0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1dff0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1e000 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1e010 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1e020 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
1e030 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1e040 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1e050 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1e060 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1e070 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
1e080 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1e090 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
1e0a0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1e0b0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
1e0c0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
1e0d0 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
1e0e0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1e0f0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1e100 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1e110 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1e120 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1e130 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1e140 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1e150 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1e160 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
1e170 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1e180 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1e190 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1e1a0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
1e1b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1e1c0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
1e1d0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1e1e0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1e1f0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1e200 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1e210 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1e220 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
1e230 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
1e240 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
1e250 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1e260 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
1e270 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
1e280 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
1e290 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
1e2a0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1e2b0 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
1e2c0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
1e2d0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
1e2e0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
1e2f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52 45  );../*.** CAPIRE
1e300 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
1e310 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b 46 31 33  atement SQL {F13
1e320 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  100}.**.** This 
1e330 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
1e340 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
1e350 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f  e a saved copy o
1e360 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a  f the original.*
1e370 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
1e380 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65  to create a [pre
1e390 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1e3a0 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65   if that stateme
1e3b0 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c  nt was.** compil
1e3c0 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
1e3d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e3e0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
1e3f0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1e400 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
1e410 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ANTS:.**.** {F13
1e420 31 30 31 7d 20 49 66 20 74 68 65 20 5b 70 72 65  101} If the [pre
1e430 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1e440 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 61   passed as the a
1e450 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20  rgument to.**   
1e460 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1e470 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69  sql()] was compi
1e480 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
1e490 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e4a0 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 20 20  e_v2()] or.**   
1e4b0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1e4c0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c  prepare16_v2()],
1e4d0 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73   then [sqlite3_s
1e4e0 71 6c 28 29 5d 20 72 65 74 75 72 6e 73 0a 2a 2a  ql()] returns.**
1e4f0 20 20 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e            a poin
1e500 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
1e510 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20  rminated string 
1e520 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20 55 54 46  containing a UTF
1e530 2d 38 20 72 65 6e 64 65 72 69 6e 67 0a 2a 2a 20  -8 rendering.** 
1e540 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
1e550 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 73 74 61  original SQL sta
1e560 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46  tement..**.** {F
1e570 31 33 31 30 32 7d 20 49 66 20 74 68 65 20 5b 70  13102} If the [p
1e580 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1e590 74 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65  t] passed as the
1e5a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
1e5b0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1e5c0 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d  3_sql()] was com
1e5d0 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
1e5e0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
1e5f0 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  are()] or.**    
1e600 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70        [sqlite3_p
1e610 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65  repare16()], the
1e620 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29  n [sqlite3_sql()
1e630 5d 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ] returns a NULL
1e640 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1e650 7b 46 31 33 31 30 33 7d 20 54 68 65 20 73 74 72  {F13103} The str
1e660 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20  ing returned by 
1e670 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 53 29 5d  [sqlite3_sql(S)]
1e680 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
1e690 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1e6a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1e6b0 65 6e 74 5d 20 53 20 69 73 20 64 65 6c 65 74 65  ent] S is delete
1e6c0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1e6d0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a  _finalize(S)]..*
1e6e0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
1e6f0 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
1e700 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
1e710 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e720 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
1e730 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 20  ed Value Object 
1e740 7b 46 31 35 30 30 30 7d 0a 2a 2a 20 4b 45 59 57  {F15000}.** KEYW
1e750 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
1e760 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
1e770 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
1e780 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
1e790 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
1e7a0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
1e7b0 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
1e7c0 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
1e7d0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
1e7e0 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
1e7f0 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
1e800 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
1e810 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
1e820 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
1e830 2e 20 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20  . Values stored 
1e840 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
1e850 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20   objects.** can 
1e860 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
1e870 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
1e880 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
1e890 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  Bs, or NULL..**.
1e8a0 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61  ** An sqlite3_va
1e8b0 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62  lue object may b
1e8c0 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63  e either "protec
1e8d0 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65  ted" or "unprote
1e8e0 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69  cted"..** Some i
1e8f0 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
1e900 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  e a protected sq
1e910 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74  lite3_value.  Ot
1e920 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  her interfaces.*
1e930 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69  * will accept ei
1e940 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64  ther a protected
1e950 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74   or an unprotect
1e960 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1e970 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72  ..** Every inter
1e980 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74  face that accept
1e990 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  s sqlite3_value 
1e9a0 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66  arguments specif
1e9b0 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  ies.** whether o
1e9c0 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65  r not it require
1e9d0 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  s a protected sq
1e9e0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
1e9f0 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
1ea00 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
1ea10 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
1ea20 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
1ea30 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
1ea40 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e   held.  A intern
1ea50 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  al mutex is held
1ea60 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64   for a protected
1ea70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
1ea80 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20  e object but no 
1ea90 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
1eaa0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
1eab0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
1eac0 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51  e object.  If SQ
1ead0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1eae0 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68   to be single-th
1eaf0 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20  readed.** (with 
1eb00 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1eb10 45 3d 30 20 61 6e 64 20 77 69 74 68 20 5b 73 71  E=0 and with [sq
1eb20 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
1eb30 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29  ()] returning 0)
1eb40 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
1eb50 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
1eb60 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
1eb70 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
1eb80 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1eb90 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
1eba0 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
1ebb0 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
1ebc0 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
1ebd0 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
1ebe0 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
1ebf0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
1ec00 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
1ec10 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
1ec20 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
1ec30 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72  tween between pr
1ec40 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
1ec50 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
1ec60 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1ec70 20 65 76 65 6e 20 69 66 20 74 68 65 79 20 61 72   even if they ar
1ec80 65 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 65  e single threade
1ec90 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1eca0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1ecb0 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
1ecc0 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
1ecd0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
1ece0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
1ecf0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
1ed00 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
1ed10 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
1ed20 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
1ed30 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65  _value object re
1ed40 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
1ed50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
1ed60 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65  ue()] is unprote
1ed70 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65  cted..** Unprote
1ed80 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1ed90 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f  ue objects may o
1eda0 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
1edb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
1edc0 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ult_value()] and
1edd0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
1ede0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  alue()]..** The 
1edf0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
1ee00 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61  lob | sqlite3_va
1ee10 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69  lue_type()] fami
1ee20 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  ly of.** interfa
1ee30 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74  ces require prot
1ee40 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1ee50 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a  lue objects..*/.
1ee60 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d  typedef struct M
1ee70 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  em sqlite3_value
1ee80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ee90 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  F: SQL Function 
1eea0 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20 7b  Context Object {
1eeb0 46 31 36 30 30 31 7d 0a 2a 2a 0a 2a 2a 20 54 68  F16001}.**.** Th
1eec0 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
1eed0 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
1eee0 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
1eef0 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
1ef00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
1ef10 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e 74 65  bject.  A pointe
1ef20 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f  r to an sqlite3_
1ef30 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a  context object.*
1ef40 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73  * is always firs
1ef50 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  t parameter to [
1ef60 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
1ef70 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
1ef80 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  s]..** The appli
1ef90 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
1efa0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
1efb0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
1efc0 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69  pass this.** poi
1efd0 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74  nter through int
1efe0 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  o calls to [sqli
1eff0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c  te3_result_int |
1f000 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28   sqlite3_result(
1f010 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1f020 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
1f030 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75  t()], [sqlite3_u
1f040 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  ser_data()],.** 
1f050 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
1f060 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b  _db_handle()], [
1f070 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
1f080 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f  ata()],.** and/o
1f090 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  r [sqlite3_set_a
1f0a0 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79  uxdata()]..*/.ty
1f0b0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
1f0c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c  ite3_context sql
1f0d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f  ite3_context;../
1f0e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42  *.** CAPI3REF: B
1f0f0 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f  inding Values To
1f100 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
1f110 65 6e 74 73 20 7b 46 31 33 35 30 30 7d 0a 2a 2a  ents {F13500}.**
1f120 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74   KEYWORDS: {host
1f130 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73   parameter} {hos
1f140 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68  t parameters} {h
1f150 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
1f160 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  me}.** KEYWORDS:
1f170 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d   {SQL parameter}
1f180 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   {SQL parameters
1f190 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53  }.**.** In the S
1f1a0 51 4c 20 73 74 72 69 6e 67 73 20 69 6e 70 75 74  QL strings input
1f1b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
1f1c0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69  pare_v2()] and i
1f1d0 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20  ts variants,.** 
1f1e0 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20  literals may be 
1f1f0 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 70 61  replaced by a pa
1f200 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65 20 6f  rameter in one o
1f210 66 20 74 68 65 73 65 20 66 6f 72 6d 73 3a 0a 2a  f these forms:.*
1f220 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
1f230 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
1f240 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
1f250 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
1f260 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
1f270 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
1f280 68 65 20 70 61 72 61 6d 65 74 65 72 20 66 6f 72  he parameter for
1f290 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 4e  ms shown above N
1f2a0 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  NN is an integer
1f2b0 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64   literal,.** and
1f2c0 20 56 56 56 20 69 73 20 61 6e 20 61 6c 70 68 61   VVV is an alpha
1f2d0 2d 6e 75 6d 65 72 69 63 20 70 61 72 61 6d 65 74  -numeric paramet
1f2e0 65 72 20 6e 61 6d 65 2e 20 54 68 65 20 76 61 6c  er name. The val
1f2f0 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
1f300 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
1f310 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
1f320 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
1f330 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
1f340 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
1f350 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
1f360 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1f370 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
1f380 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  re..**.** The fi
1f390 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
1f3a0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1f3b0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73  _*() routines is
1f3c0 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69   always.** a poi
1f3d0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
1f3e0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
1f3f0 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
1f400 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1f410 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
1f420 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a   variants..**.**
1f430 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
1f440 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
1f450 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
1f460 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
1f470 2e 0a 2a 2a 20 54 68 65 20 6c 65 66 74 6d 6f 73  ..** The leftmos
1f480 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
1f490 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
1f4a0 31 2e 20 20 57 68 65 6e 20 74 68 65 20 73 61 6d  1.  When the sam
1f4b0 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
1f4c0 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
1f4d0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
1f4e0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
1f4f0 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
1f500 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
1f510 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
1f520 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
1f530 65 2e 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78 20  e..** The index 
1f540 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
1f550 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
1f560 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
1f570 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1f580 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
1f590 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
1f5a0 64 2e 20 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a  d.  The index.**
1f5b0 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
1f5c0 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
1f5d0 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54  lue of NNN..** T
1f5e0 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
1f5f0 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
1f600 6e 64 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  nd the compile-t
1f610 69 6d 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ime.** parameter
1f620 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49   SQLITE_MAX_VARI
1f630 41 42 4c 45 5f 4e 55 4d 42 45 52 20 28 64 65 66  ABLE_NUMBER (def
1f640 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29  ault value: 999)
1f650 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72  ..**.** The thir
1f660 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
1f670 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
1f680 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
1f690 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65  ..**.** In those
1f6a0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
1f6b0 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
1f6c0 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
1f6d0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
1f6e0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
1f6f0 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
1f700 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
1f710 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
1f720 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
1f730 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
1f740 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
1f750 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
1f760 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72  ..** If the four
1f770 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
1f780 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65  negative, the le
1f790 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
1f7a0 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  ng is.** the num
1f7b0 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
1f7c0 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
1f7d0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
1f7e0 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61 72  .** The fifth ar
1f7f0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
1f800 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73  3_bind_blob(), s
1f810 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1f820 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  (), and.** sqlit
1f830 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
1f840 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
1f850 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
1f860 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
1f870 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20  ** string after 
1f880 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73  SQLite has finis
1f890 68 65 64 20 77 69 74 68 20 69 74 2e 20 49 66 20  hed with it. If 
1f8a0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
1f8b0 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
1f8c0 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
1f8d0 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
1f8e0 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
1f8f0 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
1f900 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
1f910 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
1f920 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
1f930 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
1f940 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  eed..** If the f
1f950 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
1f960 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
1f970 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
1f980 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  then.** SQLite m
1f990 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69  akes its own pri
1f9a0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
1f9b0 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
1f9c0 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  y, before.** the
1f9d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
1f9e0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
1f9f0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
1fa00 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
1fa10 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
1fa20 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
1fa30 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73  gth N that.** is
1fa40 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
1fa50 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62  oes.  A zeroblob
1fa60 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
1fa70 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
1fa80 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
1fa90 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
1faa0 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
1fab0 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
1fac0 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
1fad0 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
1fae0 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
1faf0 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
1fb00 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
1fb10 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
1fb20 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
1fb30 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
1fb40 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
1fb50 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
1fb60 2a 20 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c  * A negative val
1fb70 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
1fb80 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
1fb90 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
1fba0 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  B..**.** The sql
1fbb0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1fbc0 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
1fbd0 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b  alled after.** [
1fbe0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1fbf0 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76  v2()] (and its v
1fc00 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c  ariants) or [sql
1fc10 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e  ite3_reset()] an
1fc20 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c  d.** before [sql
1fc30 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1fc40 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f   Bindings are no
1fc50 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
1fc60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1fc70 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55  )] routine..** U
1fc80 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
1fc90 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
1fca0 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
1fcb0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1fcc0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1fcd0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
1fce0 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69   an error code i
1fcf0 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f  f.** anything go
1fd00 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49  es wrong.  [SQLI
1fd10 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
1fd20 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
1fd30 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
1fd40 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
1fd50 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d    [SQLITE_NOMEM]
1fd60 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
1fd70 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
1fd80 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
1fd90 45 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  E] might be retu
1fda0 72 6e 65 64 20 69 66 20 74 68 65 73 65 20 72 6f  rned if these ro
1fdb0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
1fdc0 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61  d on a.** virtua
1fdd0 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69  l machine that i
1fde0 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74  s the wrong stat
1fdf0 65 20 6f 72 20 77 68 69 63 68 20 68 61 73 20 61  e or which has a
1fe00 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61  lready been fina
1fe10 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74  lized..** Detect
1fe20 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 73  ion of misuse is
1fe30 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 70   unreliable.  Ap
1fe40 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
1fe50 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20  d not depend.** 
1fe60 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  on SQLITE_MISUSE
1fe70 20 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 54   returns.  SQLIT
1fe80 45 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74 65  E_MISUSE is inte
1fe90 6e 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  nded to indicate
1fea0 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72   a.** a logic er
1feb0 72 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c 69  ror in the appli
1fec0 63 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 20  cation.  Future 
1fed0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1fee0 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69  te might.** pani
1fef0 63 20 72 61 74 68 65 72 20 74 68 61 6e 20 72 65  c rather than re
1ff00 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
1ff10 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  SE..**.** See al
1ff20 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
1ff30 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
1ff40 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
1ff50 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1ff60 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _name()], and [s
1ff70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1ff80 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
1ff90 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
1ffa0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 30 36 7d  :.**.** {F13506}
1ffb0 20 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65 6d   The [SQL statem
1ffc0 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 72 65  ent compiler] re
1ffd0 63 6f 67 6e 69 7a 65 73 20 74 6f 6b 65 6e 73 20  cognizes tokens 
1ffe0 6f 66 20 74 68 65 20 66 6f 72 6d 73 0a 2a 2a 20  of the forms.** 
1fff0 20 20 20 20 20 20 20 20 20 22 3f 22 2c 20 22 3f           "?", "?
20000 4e 4e 4e 22 2c 20 22 24 56 56 56 22 2c 20 22 3a  NNN", "$VVV", ":
20010 56 56 56 22 2c 20 61 6e 64 20 22 40 56 56 56 22  VVV", and "@VVV"
20020 20 61 73 20 53 51 4c 20 70 61 72 61 6d 65 74 65   as SQL paramete
20030 72 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rs,.**          
20040 77 68 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e 79  where NNN is any
20050 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65   sequence of one
20060 20 6f 72 20 6d 6f 72 65 20 64 69 67 69 74 73 0a   or more digits.
20070 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  **          and 
20080 77 68 65 72 65 20 56 56 56 20 69 73 20 61 6e 79  where VVV is any
20090 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65   sequence of one
200a0 20 6f 72 20 6d 6f 72 65 20 61 6c 70 68 61 6e 75   or more alphanu
200b0 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20  meric.**        
200c0 20 20 63 68 61 72 61 63 74 65 72 73 20 6f 72 20    characters or 
200d0 22 3a 3a 22 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  "::" optionally 
200e0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 20 73 74  followed by a st
200f0 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 0a  ring containing.
20100 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 20 73  **          no s
20110 70 61 63 65 73 20 61 6e 64 20 63 6f 6e 74 61 69  paces and contai
20120 6e 65 64 20 77 69 74 68 69 6e 20 70 61 72 65 6e  ned within paren
20130 74 68 65 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  theses..**.** {F
20140 31 33 35 30 39 7d 20 54 68 65 20 69 6e 69 74 69  13509} The initi
20150 61 6c 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53  al value of an S
20160 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
20170 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  NULL..**.** {F13
20180 35 31 32 7d 20 54 68 65 20 69 6e 64 65 78 20 6f  512} The index o
20190 66 20 61 6e 20 22 3f 22 20 53 51 4c 20 70 61 72  f an "?" SQL par
201a0 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6c 61  ameter is one la
201b0 72 67 65 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a  rger than the.**
201c0 20 20 20 20 20 20 20 20 20 20 6c 61 72 67 65 73            larges
201d0 74 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70  t index of SQL p
201e0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
201f0 6c 65 66 74 2c 20 6f 72 20 31 20 69 66 0a 2a 2a  left, or 1 if.**
20200 20 20 20 20 20 20 20 20 20 20 74 68 65 20 22 3f            the "?
20210 22 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73  " is the leftmos
20220 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 2e  t SQL parameter.
20230 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31 35 7d 20  .**.** {F13515} 
20240 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  The index of an 
20250 22 3f 4e 4e 4e 22 20 53 51 4c 20 70 61 72 61 6d  "?NNN" SQL param
20260 65 74 65 72 20 69 73 20 74 68 65 20 69 6e 74 65  eter is the inte
20270 67 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b  ger NNN..**.** {
20280 46 31 33 35 31 38 7d 20 54 68 65 20 69 6e 64 65  F13518} The inde
20290 78 20 6f 66 20 61 6e 20 22 3a 56 56 56 22 2c 20  x of an ":VVV", 
202a0 22 24 56 56 56 22 2c 20 6f 72 20 22 40 56 56 56  "$VVV", or "@VVV
202b0 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  " SQL parameter 
202c0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  is.**          t
202d0 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 69  he same as the i
202e0 6e 64 65 78 20 6f 66 20 6c 65 66 74 6d 6f 73 74  ndex of leftmost
202f0 20 6f 63 63 75 72 72 65 6e 63 65 73 20 6f 66 20   occurrences of 
20300 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20  the same.**     
20310 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2c 20       parameter, 
20320 6f 72 20 6f 6e 65 20 6d 6f 72 65 20 74 68 61 6e  or one more than
20330 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64   the largest ind
20340 65 78 20 6f 76 65 72 20 61 6c 6c 0a 2a 2a 20 20  ex over all.**  
20350 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65          paramete
20360 72 73 20 74 6f 20 74 68 65 20 6c 65 66 74 20 69  rs to the left i
20370 66 20 74 68 69 73 20 69 73 20 74 68 65 20 66 69  f this is the fi
20380 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 0a 2a  rst occurrence.*
20390 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
203a0 69 73 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72  is parameter, or
203b0 20 31 20 69 66 20 74 68 69 73 20 69 73 20 74 68   1 if this is th
203c0 65 20 6c 65 66 74 6d 6f 73 74 20 70 61 72 61 6d  e leftmost param
203d0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  eter..**.** {F13
203e0 35 32 31 7d 20 54 68 65 20 5b 53 51 4c 20 73 74  521} The [SQL st
203f0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
20400 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20  ] fails with an 
20410 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 0a 2a  [SQLITE_RANGE].*
20420 2a 20 20 20 20 20 20 20 20 20 20 65 72 72 6f 72  *          error
20430 20 69 66 20 74 68 65 20 69 6e 64 65 78 20 6f 66   if the index of
20440 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
20450 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31  r is less than 1
20460 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
20470 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65  greater than the
20480 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 53 51   compile-time SQ
20490 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c  LITE_MAX_VARIABL
204a0 45 5f 4e 55 4d 42 45 52 0a 2a 2a 20 20 20 20 20  E_NUMBER.**     
204b0 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2e 0a       parameter..
204c0 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 34 7d 20 43  **.** {F13524} C
204d0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
204e0 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c  _bind_text | sql
204f0 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c  ite3_bind(S,N,V,
20500 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
20510 20 20 61 73 73 6f 63 69 61 74 65 20 74 68 65 20    associate the 
20520 76 61 6c 75 65 20 56 20 77 69 74 68 20 61 6c 6c  value V with all
20530 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
20540 68 61 76 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20  having an.**    
20550 20 20 20 20 20 20 69 6e 64 65 78 20 6f 66 20 4e        index of N
20560 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
20570 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
20580 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 37 7d 20 43  **.** {F13527} C
20590 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
205a0 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c  _bind_text | sql
205b0 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e  ite3_bind(S,N,..
205c0 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
205d0 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72 20 63  override prior c
205e0 61 6c 6c 73 20 77 69 74 68 20 74 68 65 20 73 61  alls with the sa
205f0 6d 65 20 76 61 6c 75 65 73 20 6f 66 20 53 20 61  me values of S a
20600 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  nd N..**.** {F13
20610 35 33 30 7d 20 42 69 6e 64 69 6e 67 73 20 65 73  530} Bindings es
20620 74 61 62 6c 69 73 68 65 64 20 62 79 20 5b 73 71  tablished by [sq
20630 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
20640 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53  | sqlite3_bind(S
20650 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
20660 20 20 20 70 65 72 73 69 73 74 20 61 63 72 6f 73     persist acros
20670 73 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  s calls to [sqli
20680 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a  te3_reset(S)]..*
20690 2a 0a 2a 2a 20 7b 46 31 33 35 33 33 7d 20 49 6e  *.** {F13533} In
206a0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
206b0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e  e3_bind_blob(S,N
206c0 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,L,D)],.**    
206d0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
206e0 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c  ind_text(S,N,V,L
206f0 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
20700 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
20710 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c  nd_text16(S,N,V,
20720 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e  L,D)] SQLite bin
20730 64 73 20 74 68 65 20 66 69 72 73 74 20 4c 0a 2a  ds the first L.*
20740 2a 20 20 20 20 20 20 20 20 20 20 62 79 74 65 73  *          bytes
20750 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20   of the BLOB or 
20760 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74  string pointed t
20770 6f 20 62 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a  o by V, when L.*
20780 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f  *          is no
20790 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  n-negative..**.*
207a0 2a 20 7b 46 31 33 35 33 36 7d 20 49 6e 20 63 61  * {F13536} In ca
207b0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
207c0 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c  bind_text(S,N,V,
207d0 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  L,D)] or.**     
207e0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
207f0 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c  nd_text16(S,N,V,
20800 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e  L,D)] SQLite bin
20810 64 73 20 63 68 61 72 61 63 74 65 72 73 0a 2a 2a  ds characters.**
20820 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 56            from V
20830 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
20840 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
20850 72 20 77 68 65 6e 20 4c 20 69 73 20 6e 65 67 61  r when L is nega
20860 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  tive..**.** {F13
20870 35 33 39 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  539} In calls to
20880 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
20890 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c  lob(S,N,V,L,D)],
208a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
208b0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
208c0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a  S,N,V,L,D)], or.
208d0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
208e0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
208f0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65  (S,N,V,L,D)] whe
20900 6e 20 44 20 69 73 20 74 68 65 20 73 70 65 63 69  n D is the speci
20910 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  al.**          c
20920 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f  onstant [SQLITE_
20930 53 54 41 54 49 43 5d 2c 20 53 51 4c 69 74 65 20  STATIC], SQLite 
20940 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
20950 20 76 61 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20   value V.**     
20960 20 20 20 20 20 69 73 20 68 65 6c 64 20 69 6e 20       is held in 
20970 73 74 61 74 69 63 20 75 6e 6d 61 6e 61 67 65 64  static unmanaged
20980 20 73 70 61 63 65 20 74 68 61 74 20 77 69 6c 6c   space that will
20990 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20   not change.**  
209a0 20 20 20 20 20 20 20 20 64 75 72 69 6e 67 20 74          during t
209b0 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74  he lifetime of t
209c0 68 65 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a  he binding..**.*
209d0 2a 20 7b 46 31 33 35 34 32 7d 20 49 6e 20 63 61  * {F13542} In ca
209e0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
209f0 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  bind_blob(S,N,V,
20a00 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  L,D)],.**       
20a10 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
20a20 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
20a30 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
20a40 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
20a50 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
20a60 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 65  )] when D is the
20a70 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20   special.**     
20a80 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53       constant [S
20a90 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
20aa0 2c 20 74 68 65 20 72 6f 75 74 69 6e 65 20 6d 61  , the routine ma
20ab0 6b 65 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20  kes a.**        
20ac0 20 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f    private copy o
20ad0 66 20 74 68 65 20 76 61 6c 75 65 20 56 20 62 65  f the value V be
20ae0 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
20af0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 35 7d 20  .**.** {F13545} 
20b00 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  In calls to [sql
20b10 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53  ite3_bind_blob(S
20b20 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20  ,N,V,L,D)],.**  
20b30 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
20b40 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56  _bind_text(S,N,V
20b50 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  ,L,D)], or.**   
20b60 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
20b70 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c  bind_text16(S,N,
20b80 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69  V,L,D)] when D i
20b90 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  s a pointer to.*
20ba0 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 75 6e  *          a fun
20bb0 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69 6e  ction, SQLite in
20bc0 76 6f 6b 65 73 20 74 68 61 74 20 66 75 6e 63 74  vokes that funct
20bd0 69 6f 6e 20 74 6f 20 64 65 73 74 72 6f 79 20 74  ion to destroy t
20be0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  he.**          v
20bf0 61 6c 75 65 20 56 20 61 66 74 65 72 20 69 74 20  alue V after it 
20c00 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
20c10 6e 67 20 74 68 65 20 76 61 6c 75 65 20 56 2e 0a  ng the value V..
20c20 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 38 7d 20 49  **.** {F13548} I
20c30 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
20c40 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
20c50 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 20  b(S,N,V,L)] the 
20c60 76 61 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 20  value bound.**  
20c70 20 20 20 20 20 20 20 20 69 73 20 61 20 42 4c 4f          is a BLO
20c80 42 20 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f 72  B of L bytes, or
20c90 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
20ca0 4c 4f 42 20 69 66 20 4c 20 69 73 20 6e 65 67 61  LOB if L is nega
20cb0 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  tive..**.** {F13
20cc0 35 35 31 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  551} In calls to
20cd0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
20ce0 61 6c 75 65 28 53 2c 4e 2c 56 29 5d 20 74 68 65  alue(S,N,V)] the
20cf0 20 56 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 0a   V argument may.
20d00 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 20 65  **          be e
20d10 69 74 68 65 72 20 61 20 5b 70 72 6f 74 65 63 74  ither a [protect
20d20 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
20d30 5d 20 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a 2a  ] object or an.*
20d40 2a 20 20 20 20 20 20 20 20 20 20 5b 75 6e 70 72  *          [unpr
20d50 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
20d60 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  value] object..*
20d70 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
20d80 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
20d90 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
20da0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
20db0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
20dc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
20dd0 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  d_double(sqlite3
20de0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75  _stmt*, int, dou
20df0 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ble);.int sqlite
20e00 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
20e10 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
20e20 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
20e30 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
20e40 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
20e50 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
20e60 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
20e70 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
20e80 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  mt*, int);.int s
20e90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
20ea0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
20eb0 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
20ec0 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
20ed0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
20ee0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
20ef0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
20f00 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
20f10 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
20f20 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
20f30 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
20f40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
20f50 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
20f60 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
20f70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
20f80 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
20f90 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b  t*, int, int n);
20fa0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20fb0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20  : Number Of SQL 
20fc0 50 61 72 61 6d 65 74 65 72 73 20 7b 46 31 33 36  Parameters {F136
20fd0 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00}.**.** This r
20fe0 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
20ff0 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
21000 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61  umber of [SQL pa
21010 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20  rameters].** in 
21020 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
21030 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72  ement].  SQL par
21040 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65  ameters are toke
21050 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ns of the.** for
21060 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22  m "?", "?NNN", "
21070 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f  :AAA", "$AAA", o
21080 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65  r "@AAA" that se
21090 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68  rve as.** placeh
210a0 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65  olders for value
210b0 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69  s that are [sqli
210c0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
210d0 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65  bound].** to the
210e0 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61   parameters at a
210f0 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a   later time..**.
21100 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
21110 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
21120 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
21130 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
21140 2d 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  -most).** parame
21150 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
21160 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
21170 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
21180 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
21190 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
211a0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
211b0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
211c0 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c  e ?NNN are used,
211d0 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
211e0 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
211f0 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  t..**.** See als
21200 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
21210 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
21220 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
21230 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
21240 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
21250 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
21260 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
21270 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
21280 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ANTS:.**.** {F13
21290 36 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  601} The [sqlite
212a0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
212b0 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72  _count(S)] inter
212c0 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
212d0 20 20 20 20 20 20 20 20 20 74 68 65 20 6c 61 72           the lar
212e0 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20 61 6c  gest index of al
212f0 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  l SQL parameters
21300 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   in the.**      
21310 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
21320 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30  atement] S, or 0
21330 20 69 66 20 53 20 63 6f 6e 74 61 69 6e 73 20 6e   if S contains n
21340 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  o SQL parameters
21350 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
21360 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
21370 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
21380 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
21390 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
213a0 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20   Host Parameter 
213b0 7b 46 31 33 36 32 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F13620}.**.** T
213c0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
213d0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
213e0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
213f0 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20 70 61   n-th.** [SQL pa
21400 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 20 5b 70  rameter] in a [p
21410 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21420 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  t]..** SQL param
21430 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
21440 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  m "?NNN" or ":AA
21450 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
21460 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61  "$AAA".** have a
21470 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74   name which is t
21480 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22  he string "?NNN"
21490 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
214a0 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
214b0 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  * respectively..
214c0 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
214d0 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22  s, the initial "
214e0 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22  :" or "$" or "@"
214f0 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e   or "?".** is in
21500 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f  cluded as part o
21510 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50  f the name..** P
21520 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
21530 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75   form "?" withou
21540 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  t a following in
21550 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61  teger have no na
21560 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 61 6c  me.** and are al
21570 73 6f 20 72 65 66 65 72 72 65 64 20 74 6f 20 61  so referred to a
21580 73 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  s "anonymous par
21590 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20  ameters"..**.** 
215a0 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
215b0 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
215c0 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
215d0 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  0..**.** If the 
215e0 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f  value n is out o
215f0 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
21600 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e n-th parameter
21610 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c   is.** nameless,
21620 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
21630 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74  turned.  The ret
21640 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
21650 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
21660 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
21670 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
21680 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
21690 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
216a0 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
216b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
216c0 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
216d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
216e0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
216f0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
21700 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
21710 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
21720 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
21730 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
21740 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
21750 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
21760 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ndex()]..**.** I
21770 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
21780 20 7b 46 31 33 36 32 31 7d 20 54 68 65 20 5b 73   {F13621} The [s
21790 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
217a0 6d 65 74 65 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d  meter_name(S,N)]
217b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
217c0 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ns.**          a
217d0 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
217e0 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   of the name of 
217f0 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
21800 72 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  r in.**         
21810 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
21820 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 76 69  tatement] S havi
21830 6e 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a  ng index N, or.*
21840 2a 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  *          NULL 
21850 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 53  if there is no S
21860 51 4c 20 70 61 72 61 6d 65 74 65 72 20 77 69 74  QL parameter wit
21870 68 20 69 6e 64 65 78 20 4e 20 6f 72 20 69 66 20  h index N or if 
21880 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
21890 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 69  parameter with i
218a0 6e 64 65 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f  ndex N is an ano
218b0 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
218c0 20 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63   "?"..*/.const c
218d0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
218e0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
218f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
21900 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
21910 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
21920 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
21930 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 46   A Given Name {F
21940 31 33 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74  13640}.**.** Ret
21950 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
21960 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
21970 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
21980 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20  .  The.** index 
21990 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
219a0 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
219b0 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
219c0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
219d0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
219e0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
219f0 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20  ()].  A zero.** 
21a00 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
21a10 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
21a20 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
21a30 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
21a40 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
21a50 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
21a60 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
21a70 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
21a80 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
21a90 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
21aa0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
21ab0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
21ac0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
21ad0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
21ae0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
21af0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
21b00 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
21b10 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
21b20 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
21b30 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
21b40 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
21b50 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 34 31 7d 20  .**.** {F13641} 
21b60 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  The [sqlite3_bin
21b70 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
21b80 78 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  x(S,N)] interfac
21b90 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
21ba0 20 20 20 20 20 20 74 68 65 20 69 6e 64 65 78 20        the index 
21bb0 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  of SQL parameter
21bc0 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
21bd0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
21be0 20 20 20 20 20 20 20 20 20 53 20 77 68 6f 73 65           S whose
21bf0 20 6e 61 6d 65 20 6d 61 74 63 68 65 73 20 74 68   name matches th
21c00 65 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 4e  e UTF-8 string N
21c10 2c 20 6f 72 20 30 20 69 66 20 74 68 65 72 65 20  , or 0 if there 
21c20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  is.**          n
21c30 6f 20 6d 61 74 63 68 2e 0a 2a 2f 0a 69 6e 74 20  o match..*/.int 
21c40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
21c50 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
21c60 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
21c70 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
21c80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21c90 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
21ca0 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
21cb0 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33  d Statement {F13
21cc0 36 36 30 7d 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72  660}.**.** Contr
21cd0 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
21ce0 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
21cf0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
21d00 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a  does not reset.*
21d10 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
21d20 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
21d30 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61  ngs] on a [prepa
21d40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
21d50 2a 2a 20 55 73 65 20 74 68 69 73 20 72 6f 75 74  ** Use this rout
21d60 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
21d70 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
21d80 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
21d90 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
21da0 2a 20 7b 46 31 33 36 36 31 7d 20 54 68 65 20 5b  * {F13661} The [
21db0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
21dc0 6e 64 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 72  ndings(S)] inter
21dd0 66 61 63 65 20 72 65 73 65 74 73 20 61 6c 6c 20  face resets all 
21de0 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  SQL.**          
21df0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
21e00 67 73 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  gs in the [prepa
21e10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
21e20 20 62 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a   back to NULL..*
21e30 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
21e40 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  ear_bindings(sql
21e50 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
21e60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
21e70 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20  mber Of Columns 
21e80 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20  In A Result Set 
21e90 7b 46 31 33 37 31 30 7d 0a 2a 2a 0a 2a 2a 20 52  {F13710}.**.** R
21ea0 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
21eb0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
21ec0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
21ed0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
21ee0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
21ef0 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74  ment]. This rout
21f00 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
21f10 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c   pStmt is an SQL
21f20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68  .** statement th
21f30 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75  at does not retu
21f40 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61  rn data (for exa
21f50 6d 70 6c 65 20 61 6e 20 55 50 44 41 54 45 29 2e  mple an UPDATE).
21f60 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
21f70 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 31 31  S:.**.** {F13711
21f80 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
21f90 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20  olumn_count(S)] 
21fa0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
21fb0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
21fc0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 75  **          colu
21fd0 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
21fe0 74 20 73 65 74 20 67 65 6e 65 72 61 74 65 64 20  t set generated 
21ff0 62 79 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  by the [prepared
22000 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a   statement] S,.*
22010 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 30 20  *          or 0 
22020 69 66 20 53 20 64 6f 65 73 20 6e 6f 74 20 67 65  if S does not ge
22030 6e 65 72 61 74 65 20 61 20 72 65 73 75 6c 74 20  nerate a result 
22040 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  set..*/.int sqli
22050 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
22060 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
22070 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
22080 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
22090 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
220a0 20 53 65 74 20 7b 46 31 33 37 32 30 7d 0a 2a 2a   Set {F13720}.**
220b0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
220c0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
220d0 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
220e0 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
220f0 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
22100 75 6c 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c  ult set of a SEL
22110 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  ECT statement.  
22120 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
22130 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
22140 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
22150 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
22160 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
22170 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e  F-8 string.** an
22180 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
22190 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e  _name16() return
221a0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
221b0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
221c0 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
221d0 67 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  g.  The first pa
221e0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
221f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22200 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
22210 65 6d 65 6e 74 73 20 74 68 65 20 53 45 4c 45 43  ements the SELEC
22220 54 20 73 74 61 74 65 6d 65 6e 74 2e 20 54 68 65  T statement. The
22230 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
22240 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r is the.** colu
22250 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  mn number.  The 
22260 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
22270 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  is number 0..**.
22280 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  ** The returned 
22290 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
222a0 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
222b0 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72  ther the [prepar
222c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
222d0 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
222e0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
222f0 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
22300 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a  he next call to.
22310 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
22320 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
22330 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
22340 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  6() on the same 
22350 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  column..**.** If
22360 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
22370 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
22380 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
22390 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
223a0 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
223b0 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
223c0 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
223d0 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
223e0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
223f0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
22400 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
22410 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
22420 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
22430 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
22440 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
22450 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
22460 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
22470 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
22480 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
22490 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
224a0 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
224b0 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
224c0 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
224d0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
224e0 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
224f0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
22500 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 31 7d  :.**.** {F13721}
22510 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
22520 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
22530 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
22540 6e 61 6d 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20  name(S,N)].**   
22550 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
22560 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61 6d   returns the nam
22570 65 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  e of the Nth col
22580 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73 0a  umn (where 0 is.
22590 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
225a0 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29  leftmost column)
225b0 20 66 6f 72 20 74 68 65 20 72 65 73 75 6c 74 20   for the result 
225c0 73 65 74 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  set of the.**   
225d0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
225e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 73   statement] S as
225f0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
22600 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ed UTF-8 string.
22610 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 33 7d 20  .**.** {F13723} 
22620 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76  A successful inv
22630 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  ocation of the [
22640 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
22650 61 6d 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20  ame16(S,N)].**  
22660 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
22670 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61  e returns the na
22680 6d 65 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f  me of the Nth co
22690 6c 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73  lumn (where 0 is
226a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
226b0 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
226c0 29 20 66 6f 72 20 74 68 65 20 72 65 73 75 6c 74  ) for the result
226d0 20 73 65 74 20 6f 66 20 74 68 65 0a 2a 2a 20 20   set of the.**  
226e0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
226f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61  d statement] S a
22700 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
22710 74 65 64 20 55 54 46 2d 31 36 20 73 74 72 69 6e  ted UTF-16 strin
22720 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  g.**          in
22730 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
22740 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46   order..**.** {F
22750 31 33 37 32 34 7d 20 54 68 65 20 5b 73 71 6c 69  13724} The [sqli
22760 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
22770 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
22780 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 5d  column_name16()]
22790 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
227a0 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 61  erfaces return a
227b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
227c0 20 74 68 65 79 20 61 72 65 20 75 6e 61 62 6c 65   they are unable
227d0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
227e0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
227f0 74 6f 20 68 6f 6c 64 20 74 68 65 69 72 20 6e 6f  to hold their no
22800 72 6d 61 6c 20 72 65 74 75 72 6e 20 73 74 72 69  rmal return stri
22810 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  ngs..**.** {F137
22820 32 35 7d 20 49 66 20 74 68 65 20 4e 20 70 61 72  25} If the N par
22830 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
22840 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53  e3_column_name(S
22850 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  ,N)] or.**      
22860 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
22870 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  umn_name16(S,N)]
22880 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
22890 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20  , then the.**   
228a0 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
228b0 73 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20  s return a NULL 
228c0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  pointer..**.** {
228d0 46 31 33 37 32 36 7d 20 54 68 65 20 73 74 72 69  F13726} The stri
228e0 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
228f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
22900 6e 61 6d 65 28 53 2c 4e 29 5d 20 61 6e 64 0a 2a  name(S,N)] and.*
22910 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
22920 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
22930 36 28 53 2c 4e 29 5d 20 61 72 65 20 76 61 6c 69  6(S,N)] are vali
22940 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  d until the next
22950 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
22960 6c 20 74 6f 20 65 69 74 68 65 72 20 72 6f 75 74  l to either rout
22970 69 6e 65 20 77 69 74 68 20 74 68 65 20 73 61 6d  ine with the sam
22980 65 20 53 20 61 6e 64 20 4e 20 70 61 72 61 6d 65  e S and N parame
22990 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ters.**         
229a0 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
229b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20  e3_finalize(S)] 
229c0 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a  is called..**.**
229d0 20 7b 46 31 33 37 32 37 7d 20 57 68 65 6e 20 61   {F13727} When a
229e0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f   result column o
229f0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
22a00 74 65 6d 65 6e 74 20 63 6f 6e 74 61 69 6e 73 0a  tement contains.
22a10 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 41  **          an A
22a20 53 20 63 6c 61 75 73 65 2c 20 74 68 65 20 6e 61  S clause, the na
22a30 6d 65 20 6f 66 20 74 68 61 74 20 63 6f 6c 75 6d  me of that colum
22a40 6e 20 69 73 20 74 68 65 20 69 64 65 6e 74 69 66  n is the identif
22a50 69 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ier.**          
22a60 74 6f 20 74 68 65 20 72 69 67 68 74 20 6f 66 20  to the right of 
22a70 74 68 65 20 41 53 20 6b 65 79 77 6f 72 64 2e 0a  the AS keyword..
22a80 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
22a90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
22aa0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
22ab0 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20  , int N);.const 
22ac0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
22ad0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
22ae0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
22af0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
22b00 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
22b10 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
22b20 73 75 6c 74 20 7b 46 31 33 37 34 30 7d 0a 2a 2a  sult {F13740}.**
22b30 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
22b40 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
22b50 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
22b60 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77  what column of w
22b70 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20  hat.** table in 
22b80 77 68 69 63 68 20 64 61 74 61 62 61 73 65 20 61  which database a
22b90 20 72 65 73 75 6c 74 20 6f 66 20 61 20 53 45 4c   result of a SEL
22ba0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ECT statement co
22bb0 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65  mes from..** The
22bc0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
22bd0 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
22be0 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
22bf0 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
22c00 69 74 68 65 72 20 61 20 55 54 46 38 20 6f 72 20  ither a UTF8 or 
22c10 55 54 46 31 36 20 73 74 72 69 6e 67 2e 20 20 54  UTF16 string.  T
22c20 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
22c30 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
22c40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
22c50 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
22c60 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
22c70 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
22c80 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
22c90 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
22ca0 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
22cb0 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  me..** The retur
22cc0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
22cd0 6c 69 64 20 75 6e 74 69 6c 0a 2a 2a 20 74 68 65  lid until.** the
22ce0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
22cf0 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
22d00 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
22d10 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
22d20 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
22d30 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
22d40 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
22d50 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
22d60 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
22d70 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20 72 65  .** The names re
22d80 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
22d90 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
22da0 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
22db0 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
22dc0 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
22dd0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
22de0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
22df0 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20  following calls 
22e00 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
22e10 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68  tatement]..** Th
22e20 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
22e30 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
22e40 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 63   about the Nth c
22e50 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
22e60 79 20 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  y .** the statem
22e70 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
22e80 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
22e90 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
22ea0 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20 63  .** If the Nth c
22eb0 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
22ec0 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
22ed0 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
22ee0 0a 2a 2a 20 6f 72 20 73 75 62 71 75 65 72 79 20  .** or subquery 
22ef0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
22f00 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
22f10 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
22f20 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e  ctions.** return
22f30 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 72 6f   NULL.  These ro
22f40 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
22f50 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
22f60 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  a memory.** allo
22f70 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
22f80 75 72 73 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  urs.  Otherwise,
22f90 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
22fa0 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65   .** name of the
22fb0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
22fc0 73 65 2c 20 74 61 62 6c 65 20 61 6e 64 20 63 6f  se, table and co
22fd0 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
22fe0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e  result.** column
22ff0 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
23000 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69  rom..**.** As wi
23010 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
23020 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
23030 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 20 22  postfixed with "
23040 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
23050 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
23060 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20  ings, the other 
23070 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
23080 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a   UTF-8. {END}.**
23090 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 61  .** These APIs a
230a0 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
230b0 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
230c0 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
230d0 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
230e0 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
230f0 4d 45 54 41 44 41 54 41 20 70 72 65 70 72 6f 63  METADATA preproc
23100 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66  essor symbol def
23110 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 33  ined..**.** {U13
23120 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  751}.** If two o
23130 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
23140 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
23150 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
23160 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
23170 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
23180 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
23190 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
231a0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
231b0 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
231c0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  efined..**.** IN
231d0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
231e0 7b 46 31 33 37 34 31 7d 20 54 68 65 20 5b 73 71  {F13741} The [sq
231f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
23200 61 62 61 73 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d  abase_name(S,N)]
23210 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
23220 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
23230 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20        the UTF-8 
23240 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
23250 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
23260 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20  base from which 
23270 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  the .**         
23280 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
23290 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  mn of [prepared 
232a0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a  statement] S .**
232b0 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78 74            is ext
232c0 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20  racted, or NULL 
232d0 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
232e0 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20  n of S is a.**  
232f0 20 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20          general 
23300 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66  expression or if
23310 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
23320 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20  ate memory.**   
23330 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20         to store 
23340 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20  the name..**    
23350 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34        .** {F1374
23360 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
23370 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
23380 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74  name16(S,N)] int
23390 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
233a0 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
233b0 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74    the UTF-16 nat
233c0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a  ive byte order.*
233d0 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d  *          zero-
233e0 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20  terminated name 
233f0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
23400 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 0a  from which the .
23410 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
23420 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
23430 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23440 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20 20 20  ment] S .**     
23450 20 20 20 20 20 69 73 20 65 78 74 72 61 63 74 65       is extracte
23460 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
23470 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
23480 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  S is a.**       
23490 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65     general expre
234a0 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62  ssion or if unab
234b0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
234c0 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20  emory.**        
234d0 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e    to store the n
234e0 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ame..**         
234f0 20 0a 2a 2a 20 7b 46 31 33 37 34 33 7d 20 54 68   .** {F13743} Th
23500 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
23510 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e  n_table_name(S,N
23520 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
23530 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
23540 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d          the UTF-
23550 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
23560 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61  d name of the ta
23570 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74  ble from which t
23580 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  he .**          
23590 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
235a0 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  n of [prepared s
235b0 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20  tatement] S .** 
235c0 20 20 20 20 20 20 20 20 20 69 73 20 65 78 74 72           is extr
235d0 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69  acted, or NULL i
235e0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
235f0 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20   of S is a.**   
23600 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65         general e
23610 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20  xpression or if 
23620 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
23630 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20  te memory.**    
23640 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74        to store t
23650 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20  he name..**     
23660 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 34       .** {F13744
23670 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
23680 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
23690 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
236a0 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
236b0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
236c0 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  e UTF-16 native 
236d0 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
236e0 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
236f0 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
23700 68 65 20 74 61 62 6c 65 20 66 72 6f 6d 20 77 68  he table from wh
23710 69 63 68 20 74 68 65 20 0a 2a 2a 20 20 20 20 20  ich the .**     
23720 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20       Nth result 
23730 63 6f 6c 75 6d 6e 20 6f 66 20 5b 70 72 65 70 61  column of [prepa
23740 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
23750 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73   .**          is
23760 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e   extracted, or N
23770 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63  ULL if the Nth c
23780 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 0a  olumn of S is a.
23790 2a 2a 20 20 20 20 20 20 20 20 20 20 67 65 6e 65  **          gene
237a0 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  ral expression o
237b0 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
237c0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a  llocate memory.*
237d0 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73 74  *          to st
237e0 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a  ore the name..**
237f0 20 20 20 20 20 20 20 20 20 20 0a 2a 2a 20 7b 46            .** {F
23800 31 33 37 34 35 7d 20 54 68 65 20 5b 73 71 6c 69  13745} The [sqli
23810 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
23820 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74  n_name(S,N)] int
23830 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
23840 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
23850 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f    the UTF-8 zero
23860 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65  -terminated name
23870 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
23880 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68 20  lumn from which 
23890 74 68 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  the .**         
238a0 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
238b0 6d 6e 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  mn of [prepared 
238c0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a  statement] S .**
238d0 20 20 20 20 20 20 20 20 20 20 69 73 20 65 78 74            is ext
238e0 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20  racted, or NULL 
238f0 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
23900 6e 20 6f 66 20 53 20 69 73 20 61 0a 2a 2a 20 20  n of S is a.**  
23910 20 20 20 20 20 20 20 20 67 65 6e 65 72 61 6c 20          general 
23920 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66  expression or if
23930 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
23940 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20  ate memory.**   
23950 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20         to store 
23960 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20  the name..**    
23970 20 20 20 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34        .** {F1374
23980 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  6} The [sqlite3_
23990 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
239a0 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  me16(S,N)] inter
239b0 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
239c0 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
239d0 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76  the UTF-16 nativ
239e0 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
239f0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
23a00 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66  rminated name of
23a10 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
23a20 6e 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  n from which the
23a30 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74   .**          Nt
23a40 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
23a50 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
23a60 74 65 6d 65 6e 74 5d 20 53 20 0a 2a 2a 20 20 20  tement] S .**   
23a70 20 20 20 20 20 20 20 69 73 20 65 78 74 72 61 63         is extrac
23a80 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20  ted, or NULL if 
23a90 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
23aa0 66 20 53 20 69 73 20 61 0a 2a 2a 20 20 20 20 20  f S is a.**     
23ab0 20 20 20 20 20 67 65 6e 65 72 61 6c 20 65 78 70       general exp
23ac0 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e  ression or if un
23ad0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
23ae0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20   memory.**      
23af0 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65      to store the
23b00 20 6e 61 6d 65 2e 0a 2a 2a 20 20 20 20 20 20 20   name..**       
23b10 20 20 20 0a 2a 2a 20 7b 46 31 33 37 34 38 7d 20     .** {F13748} 
23b20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
23b30 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20  s from.**       
23b40 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
23b50 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
23b60 7c 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61  |column metadata
23b70 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
23b80 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61 6c           are val
23b90 69 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  id.**          f
23ba0 6f 72 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  or the lifetime 
23bb0 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  of the [prepared
23bc0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20   statement].**  
23bd0 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69 6c          or until
23be0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
23bf0 20 63 68 61 6e 67 65 64 20 62 79 20 61 6e 6f 74   changed by anot
23c00 68 65 72 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  her metadata.** 
23c10 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
23c20 63 65 20 63 61 6c 6c 20 66 6f 72 20 74 68 65 20  ce call for the 
23c30 73 61 6d 65 20 70 72 65 70 61 72 65 64 20 73 74  same prepared st
23c40 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
23c50 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41  mn..**.** LIMITA
23c60 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31  TIONS:.**.** {U1
23c70 33 37 35 31 7d 20 49 66 20 74 77 6f 20 6f 72 20  3751} If two or 
23c80 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
23c90 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  l one or more.**
23ca0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
23cb0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
23cc0 73 65 5f 6e 61 6d 65 7c 63 6f 6c 75 6d 6e 20 6d  se_name|column m
23cd0 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63  etadata interfac
23ce0 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  es].**          
23cf0 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
23d00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
23d10 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
23d20 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74 20 74  **          at t
23d30 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
23d40 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
23d50 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
23d60 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
23d70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
23d80 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
23d90 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
23da0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
23db0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
23dc0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
23dd0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
23de0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
23df0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
23e00 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
23e10 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
23e20 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
23e30 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
23e40 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
23e50 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
23e60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
23e70 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
23e80 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
23e90 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
23ea0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
23eb0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
23ec0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
23ed0 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
23ee0 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
23ef0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b  A Query Result {
23f00 46 31 33 37 36 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F13760}.**.** Th
23f10 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
23f20 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
23f30 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 0a 2a 2a   statement]. .**
23f40 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
23f50 6e 74 20 69 73 20 61 20 53 45 4c 45 43 54 20 73  nt is a SELECT s
23f60 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65  tatement and the
23f70 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
23f80 68 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  he .** returned 
23f90 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
23fa0 61 74 20 53 45 4c 45 43 54 20 69 73 20 61 20 74  at SELECT is a t
23fb0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
23fc0 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
23fd0 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
23fe0 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
23ff0 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
24000 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
24010 72 65 74 75 72 6e 65 64 2e 20 20 49 66 20 74 68  returned.  If th
24020 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
24030 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69  the result set i
24040 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  s an.** expressi
24050 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20  on or subquery, 
24060 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  then a NULL poin
24070 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
24080 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64  .** The returned
24090 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
240a0 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
240b0 20 20 7b 45 4e 44 7d 20 0a 2a 2a 20 46 6f 72 20    {END} .** For 
240c0 65 78 61 6d 70 6c 65 2c 20 69 6e 20 74 68 65 20  example, in the 
240d0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
240e0 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
240f0 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
24100 54 29 3b 0a 2a 2a 0a 2a 2a 20 41 6e 64 20 74 68  T);.**.** And th
24110 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
24120 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 64 3a 0a  ement compiled:.
24130 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
24140 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
24150 0a 2a 2a 0a 2a 2a 20 54 68 65 6e 20 74 68 69 73  .**.** Then this
24160 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
24170 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
24180 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
24190 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 72 65 73  he second.** res
241a0 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  ult column (i==1
241b0 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
241c0 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
241d0 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
241e0 6e 0a 2a 2a 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a  n.** (i==0)..**.
241f0 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  ** SQLite uses d
24200 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
24210 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74  typing.  So just
24220 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
24230 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
24240 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
24250 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
24260 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
24270 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
24280 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
24290 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
242a0 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
242b0 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
242c0 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
242d0 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
242e0 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
242f0 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f   Type.** is asso
24300 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
24310 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
24320 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
24330 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
24340 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
24350 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ues..**.** INVAR
24360 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
24370 33 37 36 31 7d 20 20 41 20 73 75 63 63 65 73 73  3761}  A success
24380 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
24390 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
243a0 74 79 70 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20  type(S,N)].**   
243b0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
243c0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
243d0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 63  d UTF-8 string c
243e0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a  ontaining the.**
243f0 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 64             the d
24400 65 63 6c 61 72 65 64 20 64 61 74 61 74 79 70 65  eclared datatype
24410 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
24420 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72  lumn that appear
24430 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61  s.**           a
24440 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  s the Nth column
24450 20 28 6e 75 6d 62 65 72 65 64 20 66 72 6f 6d 20   (numbered from 
24460 30 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  0) of the result
24470 20 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20   set to the.**  
24480 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
24490 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
244a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36 32 7d 20  .**.** {F13762} 
244b0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
244c0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
244d0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
244e0 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  (S,N)].**       
244f0 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 7a 65      returns a ze
24500 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
24510 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
24520 20 6f 72 64 65 72 20 73 74 72 69 6e 67 0a 2a 2a   order string.**
24530 20 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 61             conta
24540 69 6e 69 6e 67 20 74 68 65 20 64 65 63 6c 61 72  ining the declar
24550 65 64 20 64 61 74 61 74 79 70 65 20 6f 66 20 74  ed datatype of t
24560 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
24570 74 68 61 74 20 61 70 70 65 61 72 73 0a 2a 2a 20  that appears.** 
24580 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65            as the
24590 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d   Nth column (num
245a0 62 65 72 65 64 20 66 72 6f 6d 20 30 29 20 6f 66  bered from 0) of
245b0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
245c0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
245d0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
245e0 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a  atement] S..**.*
245f0 2a 20 7b 46 31 33 37 36 33 7d 20 20 49 66 20 4e  * {F13763}  If N
24600 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 30 20   is less than 0 
24610 6f 72 20 4e 20 69 73 20 67 72 65 61 74 65 72 20  or N is greater 
24620 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
24630 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
24640 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
24650 6d 6e 73 20 69 6e 20 5b 70 72 65 70 61 72 65 64  mns in [prepared
24660 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
24670 20 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66             or if
24680 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
24690 6f 66 20 53 20 69 73 20 61 6e 20 65 78 70 72 65  of S is an expre
246a0 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
246b0 79 20 72 61 74 68 65 72 0a 2a 2a 20 20 20 20 20  y rather.**     
246c0 20 20 20 20 20 20 74 68 61 6e 20 61 20 74 61 62        than a tab
246d0 6c 65 20 63 6f 6c 75 6d 6e 20 6f 72 20 69 66 20  le column or if 
246e0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
246f0 69 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a 20 20  ion failure.**  
24700 20 20 20 20 20 20 20 20 20 6f 63 63 75 72 73 20           occurs 
24710 64 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20  during encoding 
24720 63 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74 68 65  conversions, the
24730 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63  n.**           c
24740 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
24750 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
24760 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  (S,N)] or.**    
24770 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
24780 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
24790 36 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 20 4e  6(S,N)] return N
247a0 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ULL..*/.const ch
247b0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
247c0 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
247d0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
247e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
247f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
24800 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
24810 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 20 0a 2a  mt*,int);../* .*
24820 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 76 61  * CAPI3REF:  Eva
24830 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
24840 74 65 6d 65 6e 74 20 7b 46 31 33 32 30 30 7d 0a  tement {F13200}.
24850 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 6e 20 5b  **.** After an [
24860 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24870 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
24880 70 61 72 65 64 20 77 69 74 68 20 61 20 63 61 6c  pared with a cal
24890 6c 0a 2a 2a 20 74 6f 20 65 69 74 68 65 72 20 5b  l.** to either [
248a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
248b0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
248c0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
248d0 5d 20 6f 72 20 74 6f 20 6f 6e 65 20 6f 66 0a 2a  ] or to one of.*
248e0 2a 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  * the legacy int
248f0 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
24900 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
24910 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
24920 36 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  6()],.** then th
24930 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  is function must
24940 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
24950 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
24960 65 76 61 6c 75 61 74 65 20 74 68 65 20 0a 2a 2a  evaluate the .**
24970 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
24980 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
24990 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
249a0 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 73 74   this sqlite3_st
249b0 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
249c0 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
249d0 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
249e0 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
249f0 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
24a00 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
24a10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
24a20 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
24a30 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
24a40 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
24a50 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
24a60 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
24a70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
24a80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
24a90 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
24aa0 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
24ab0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
24ac0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
24ad0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
24ae0 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
24af0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
24b00 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
24b10 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
24b20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
24b30 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
24b40 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
24b50 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
24b60 5f 42 55 53 59 5d 2c 20 0a 2a 2a 20 5b 53 51 4c  _BUSY], .** [SQL
24b70 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
24b80 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
24b90 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
24ba0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
24bb0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
24bc0 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
24bd0 74 68 65 20 6f 74 68 65 72 20 5b 53 51 4c 49 54  the other [SQLIT
24be0 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f  E_OK | result co
24bf0 64 65 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  de].** or [SQLIT
24c00 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
24c10 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
24c20 6f 64 65 5d 20 6d 69 67 68 74 20 62 65 20 72 65  ode] might be re
24c30 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 77 65 6c  turned as.** wel
24c40 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  l..**.** [SQLITE
24c50 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
24c60 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
24c70 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
24c80 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
24c90 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
24ca0 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
24cb0 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68   its job.  If th
24cc0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
24cd0 20 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72 20 6f 63   COMMIT.** or oc
24ce0 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
24cf0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
24d00 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
24d10 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
24d20 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
24d30 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
24d40 69 73 20 6e 6f 74 20 61 20 43 4f 4d 4d 49 54 20  is not a COMMIT 
24d50 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
24d60 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20  n a.** explicit 
24d70 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
24d80 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
24d90 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
24da0 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
24db0 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
24dc0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d   [SQLITE_DONE] m
24dd0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
24de0 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
24df0 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
24e00 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
24e10 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
24e20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
24e30 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
24e40 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
24e50 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
24e60 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
24e70 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
24e80 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
24e90 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
24ea0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
24eb0 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49  l state..**.** I
24ec0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
24ed0 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
24ee0 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
24ef0 61 74 61 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 53  ata, then .** [S
24f00 51 4c 49 54 45 5f 52 4f 57 5d 20 69 73 20 72 65  QLITE_ROW] is re
24f10 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
24f20 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
24f30 74 61 20 69 73 20 72 65 61 64 79 0a 2a 2a 20 66  ta is ready.** f
24f40 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
24f50 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 54 68 65   the caller. The
24f60 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
24f70 63 63 65 73 73 65 64 20 75 73 69 6e 67 0a 2a 2a  ccessed using.**
24f80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
24f90 6c 75 6d 6e 5f 69 6e 74 20 7c 20 63 6f 6c 75 6d  lumn_int | colum
24fa0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
24fb0 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
24fc0 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
24fd0 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
24fe0 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
24ff0 6f 66 20 64 61 74 61 2e 0a 2a 2a 20 0a 2a 2a 20  of data..** .** 
25000 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d  [SQLITE_ERROR] m
25010 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d  eans that a run-
25020 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68  time error (such
25030 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   as a constraint
25040 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68  .** violation) h
25050 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71  as occurred.  sq
25060 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
25070 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
25080 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68  d again on.** th
25090 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72  e VM. More infor
250a0 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f  mation may be fo
250b0 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  und by calling [
250c0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
250d0 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 6c  ]..** With the l
250e0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
250f0 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
25100 20 65 72 72 6f 72 20 63 6f 64 65 20 28 65 78 61   error code (exa
25110 6d 70 6c 65 3a 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple:.** [SQLITE
25120 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
25130 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
25140 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
25150 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
25160 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
25170 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
25180 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
25190 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
251a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49  d statement].  I
251b0 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
251c0 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
251d0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
251e0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
251f0 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
25200 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
25210 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
25220 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
25230 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
25240 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
25250 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
25260 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
25270 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
25280 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
25290 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
252a0 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
252b0 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
252c0 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
252d0 20 74 68 61 74 20 68 61 64 20 0a 2a 2a 20 70 72   that had .** pr
252e0 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
252f0 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
25300 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
25310 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
25320 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
25330 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
25340 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25350 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
25360 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
25370 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
25380 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
25390 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ime..**.** <b>Go
253a0 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
253b0 65 72 74 3a 3c 2f 62 3e 0a 2a 2a 20 49 6e 20 74  ert:</b>.** In t
253c0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
253d0 61 63 65 2c 20 0a 2a 2a 20 74 68 65 20 73 71 6c  ace, .** the sql
253e0 69 74 65 33 5f 73 74 65 70 28 29 20 41 50 49 20  ite3_step() API 
253f0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
25400 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
25410 6f 64 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ode,.** [SQLITE_
25420 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
25430 67 20 61 6e 79 20 65 72 72 6f 72 20 6f 74 68 65  g any error othe
25440 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
25450 55 53 59 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c  USY].** and [SQL
25460 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
25470 75 20 6d 75 73 74 20 63 61 6c 6c 20 5b 73 71 6c  u must call [sql
25480 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
25490 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
254a0 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
254b0 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
254c0 20 74 68 65 20 73 70 65 63 69 66 69 63 0a 2a 2a   the specific.**
254d0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
254e0 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
254f0 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
25500 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
25510 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
25520 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
25530 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
25540 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
25550 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
25560 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
25570 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
25580 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
25590 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
255a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
255b0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
255c0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
255d0 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
255e0 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
255f0 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
25600 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
25610 31 36 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  16()], then the 
25620 0a 2a 2a 20 6d 6f 72 65 20 73 70 65 63 69 66 69  .** more specifi
25630 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
25640 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
25650 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
25660 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
25670 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22   use of the "v2"
25680 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
25690 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
256a0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
256b0 2a 2a 20 7b 46 31 33 32 30 32 7d 20 20 49 66 20  ** {F13202}  If 
256c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
256d0 65 6e 74 5d 20 53 20 69 73 20 72 65 61 64 79 20  ent] S is ready 
256e0 74 6f 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20  to be.**        
256f0 20 20 20 72 75 6e 2c 20 74 68 65 6e 20 5b 73 71     run, then [sq
25700 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 61  lite3_step(S)] a
25710 64 76 61 6e 63 65 73 20 74 68 61 74 20 70 72 65  dvances that pre
25720 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
25730 2a 2a 20 20 20 20 20 20 20 20 20 20 20 75 6e 74  **           unt
25740 69 6c 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  il to completion
25750 20 6f 72 20 75 6e 74 69 6c 20 69 74 20 69 73 20   or until it is 
25760 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 20  ready to return 
25770 61 6e 6f 74 68 65 72 0a 2a 2a 20 20 20 20 20 20  another.**      
25780 20 20 20 20 20 72 6f 77 20 6f 66 20 74 68 65 20       row of the 
25790 72 65 73 75 6c 74 20 73 65 74 20 6f 72 20 61 6e  result set or an
257a0 20 69 6e 74 65 72 72 75 70 74 20 6f 72 20 72 75   interrupt or ru
257b0 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 6f 63 63  n-time error occ
257c0 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33  urs..**.** {F153
257d0 30 34 7d 20 20 57 68 65 6e 20 61 20 63 61 6c 6c  04}  When a call
257e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
257f0 70 28 53 29 5d 20 63 61 75 73 65 73 20 74 68 65  p(S)] causes the
25800 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b   .**           [
25810 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25820 6e 74 5d 20 53 20 74 6f 20 72 75 6e 20 74 6f 20  nt] S to run to 
25830 63 6f 6d 70 6c 65 74 69 6f 6e 2c 0a 2a 2a 20 20  completion,.**  
25840 20 20 20 20 20 20 20 20 20 74 68 65 20 66 75 6e           the fun
25850 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53  ction returns [S
25860 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a  QLITE_DONE]..**.
25870 2a 2a 20 7b 46 31 35 33 30 36 7d 20 20 57 68 65  ** {F15306}  Whe
25880 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  n a call to [sql
25890 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 73 74  ite3_step(S)] st
258a0 6f 70 73 20 62 65 63 61 75 73 65 20 69 74 20 69  ops because it i
258b0 73 20 72 65 61 64 79 0a 2a 2a 20 20 20 20 20 20  s ready.**      
258c0 20 20 20 20 20 74 6f 20 72 65 74 75 72 6e 20 61       to return a
258d0 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68  nother row of th
258e0 65 20 72 65 73 75 6c 74 20 73 65 74 2c 20 69 74  e result set, it
258f0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
25900 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f        [SQLITE_RO
25910 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30  W]..**.** {F1530
25920 38 7d 20 20 49 66 20 61 20 63 61 6c 6c 20 74 6f  8}  If a call to
25930 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
25940 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e  )] encounters an
25950 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
25960 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
25970 7c 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61  |interrupt] or a
25980 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 2c   run-time error,
25990 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74  .**           it
259a0 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
259b0 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 63 6f  opriate error co
259c0 64 65 20 74 68 61 74 20 69 73 20 6e 6f 74 20 6f  de that is not o
259d0 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  ne of.**        
259e0 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20     [SQLITE_OK], 
259f0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 6f 72  [SQLITE_ROW], or
25a00 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a   [SQLITE_DONE]..
25a10 2a 2a 0a 2a 2a 20 7b 46 31 35 33 31 30 7d 20 20  **.** {F15310}  
25a20 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  If an [sqlite3_i
25a30 6e 74 65 72 72 75 70 74 7c 69 6e 74 65 72 72 75  nterrupt|interru
25a40 70 74 5d 20 6f 72 20 72 75 6e 2d 74 69 6d 65 20  pt] or run-time 
25a50 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  error.**        
25a60 20 20 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67     occurs during
25a70 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
25a80 74 65 33 5f 73 74 65 70 28 53 29 5d 0a 2a 2a 20  te3_step(S)].** 
25a90 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 61 20            for a 
25aa0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25ab0 65 6e 74 5d 20 53 20 63 72 65 61 74 65 64 20 75  ent] S created u
25ac0 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
25ad0 20 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61    legacy interfa
25ae0 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
25af0 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20  pare()] or.**   
25b00 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
25b10 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 74 68  _prepare16()] th
25b20 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
25b30 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a  returns either.*
25b40 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  *           [SQL
25b50 49 54 45 5f 45 52 52 4f 52 5d 2c 20 5b 53 51 4c  ITE_ERROR], [SQL
25b60 49 54 45 5f 42 55 53 59 5d 2c 20 6f 72 20 5b 53  ITE_BUSY], or [S
25b70 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a  QLITE_MISUSE]..*
25b80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
25b90 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
25ba0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
25bb0 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
25bc0 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
25bd0 74 20 73 65 74 20 7b 46 31 33 37 37 30 7d 0a 2a  t set {F13770}.*
25be0 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20  *.** Return the 
25bf0 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73  number of values
25c00 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
25c10 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
25c20 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  t set..**.** INV
25c30 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
25c40 46 31 33 37 37 31 7d 20 20 41 66 74 65 72 20 61  F13771}  After a
25c50 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
25c60 33 5f 73 74 65 70 28 53 29 5d 20 74 68 61 74 20  3_step(S)] that 
25c70 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
25c80 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57       [SQLITE_ROW
25c90 5d 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ], the [sqlite3_
25ca0 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72  data_count(S)] r
25cb0 6f 75 74 69 6e 65 0a 2a 2a 20 20 20 20 20 20 20  outine.**       
25cc0 20 20 20 20 77 69 6c 6c 20 72 65 74 75 72 6e 20      will return 
25cd0 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 61  the same value a
25ce0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
25cf0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
25d00 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 66 75 6e  mn_count(S)] fun
25d10 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ction..**.** {F1
25d20 33 37 37 32 7d 20 20 41 66 74 65 72 20 5b 73 71  3772}  After [sq
25d30 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
25d40 61 73 20 72 65 74 75 72 6e 65 64 20 61 6e 79 20  as returned any 
25d50 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
25d60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53  .**           [S
25d70 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 62 65  QLITE_ROW] or be
25d80 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  fore [sqlite3_st
25d90 65 70 28 53 29 5d 20 68 61 73 20 62 65 65 6e 20  ep(S)] has been 
25da0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 61  .**           ca
25db0 6c 6c 65 64 20 6f 6e 20 74 68 65 20 5b 70 72 65  lled on the [pre
25dc0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25dd0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
25de0 20 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65    the first time
25df0 20 73 69 6e 63 65 20 69 74 20 77 61 73 20 5b 73   since it was [s
25e00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 7c 70  qlite3_prepare|p
25e10 72 65 70 61 72 65 64 5d 0a 2a 2a 20 20 20 20 20  repared].**     
25e20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65        or [sqlite
25e30 33 5f 72 65 73 65 74 7c 72 65 73 65 74 5d 2c 20  3_reset|reset], 
25e40 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  the [sqlite3_dat
25e50 61 5f 63 6f 75 6e 74 28 53 29 5d 0a 2a 2a 20 20  a_count(S)].**  
25e60 20 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65           routine
25e70 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
25e80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61  /.int sqlite3_da
25e90 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  ta_count(sqlite3
25ea0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
25eb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25ec0 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61  Fundamental Data
25ed0 74 79 70 65 73 20 7b 46 31 30 32 36 35 7d 0a 2a  types {F10265}.*
25ee0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
25ef0 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 46  TE_TEXT.**.** {F
25f00 31 30 32 36 36 7d 45 76 65 72 79 20 76 61 6c 75  10266}Every valu
25f10 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
25f20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
25f30 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
25f40 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
25f50 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
25f60 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
25f70 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
25f80 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
25f90 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
25fa0 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
25fb0 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
25fc0 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a  * </ul> {END}.**
25fd0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
25fe0 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
25ff0 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
26000 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
26010 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
26020 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
26030 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
26040 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
26050 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
26060 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
26070 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
26080 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
26090 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
260a0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
260b0 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
260c0 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
260d0 51 4c 49 54 45 33 5f 54 45 58 54 20 6e 6f 74 0a  QLITE3_TEXT not.
260e0 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
260f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
26100 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
26110 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
26120 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
26130 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
26140 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
26150 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
26160 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
26170 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
26180 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
26190 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
261a0 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
261b0 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
261c0 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
261d0 33 52 45 46 3a 20 52 65 73 75 6c 74 73 20 56 61  3REF: Results Va
261e0 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
261f0 79 20 7b 46 31 33 38 30 30 7d 0a 2a 2a 0a 2a 2a  y {F13800}.**.**
26200 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
26210 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74  form the "result
26220 20 73 65 74 20 71 75 65 72 79 22 20 69 6e 74 65   set query" inte
26230 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
26240 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
26250 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
26260 62 6f 75 74 0a 2a 2a 20 61 20 73 69 6e 67 6c 65  bout.** a single
26270 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
26280 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 72 6f  urrent result ro
26290 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 49  w of a query.  I
262a0 6e 20 65 76 65 72 79 0a 2a 2a 20 63 61 73 65 20  n every.** case 
262b0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
262c0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
262d0 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70  to the .** [prep
262e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
262f0 74 68 61 74 20 69 73 20 62 65 69 6e 67 0a 2a 2a  that is being.**
26300 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20   evaluated (the 
26310 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
26320 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
26330 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
26340 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
26350 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
26360 76 61 72 69 61 6e 74 73 29 20 61 6e 64 0a 2a 2a  variants) and.**
26370 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
26380 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
26390 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
263a0 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
263b0 61 74 69 6f 6e 20 0a 2a 2a 20 73 68 6f 75 6c 64  ation .** should
263c0 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54   be returned.  T
263d0 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
263e0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
263f0 74 20 73 65 74 0a 2a 2a 20 68 61 73 20 61 6e 20  t set.** has an 
26400 69 6e 64 65 78 20 6f 66 20 30 2e 0a 2a 2a 0a 2a  index of 0..**.*
26410 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
26420 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 63 75  tement is not cu
26430 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
26440 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
26450 20 69 66 20 74 68 65 0a 2a 2a 20 74 68 65 20 63   if the.** the c
26460 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
26470 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
26480 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
26490 69 6e 65 64 2e 20 0a 2a 2a 20 54 68 65 73 65 20  ined. .** These 
264a0 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
264b0 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
264c0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
264d0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
264e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
264f0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
26500 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
26510 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
26520 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
26530 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
26540 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 20 73   has been call s
26550 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
26560 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
26570 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
26580 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
26590 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
265a0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
265b0 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
265c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
265d0 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
265e0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
265f0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
26600 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
26610 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
26620 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
26630 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
26640 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
26650 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
26660 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
26670 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
26680 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
26690 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
266a0 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
266b0 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
266c0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
266d0 6e 65 64 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ned.  .**.** The
266e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
266f0 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72  type() routine r
26700 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
26710 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
26720 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
26730 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
26740 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
26750 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
26760 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
26770 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
26780 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
26790 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
267a0 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
267b0 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
267c0 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
267d0 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
267e0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
267f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
26800 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
26810 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
26820 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
26830 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
26840 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
26850 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
26860 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
26870 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
26880 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
26890 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
268a0 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
268b0 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
268c0 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
268d0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
268e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
268f0 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
26900 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
26910 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rsion..**.** If 
26920 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
26930 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
26940 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
26950 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
26960 65 73 28 29 20 0a 2a 2a 20 72 6f 75 74 69 6e 65  es() .** routine
26970 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
26980 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
26990 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
269a0 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72  ing..** If the r
269b0 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
269c0 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
269d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
269e0 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
269f0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
26a00 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
26a10 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
26a20 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49  r of bytes..** I
26a30 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
26a40 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
26a50 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
26a60 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
26a70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
26a80 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
26a90 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
26aa0 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
26ab0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
26ac0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
26ad0 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
26ae0 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  ng..** The value
26af0 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e   returned does n
26b00 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
26b10 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61  ero terminator a
26b20 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20  t the end.** of 
26b30 74 68 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72  the string.  For
26b40 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
26b50 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
26b60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
26b70 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
26b80 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
26b90 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
26ba0 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67  rs..**.** String
26bb0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
26bc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
26bd0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
26be0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
26bf0 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
26c00 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
26c10 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  ys zero terminat
26c20 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 0a  ed.  The return.
26c30 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
26c40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
26c50 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
26c60 65 6e 67 74 68 20 62 6c 6f 62 20 69 73 20 61 6e  ength blob is an
26c70 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f   arbitrary.** po
26c80 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20  inter, possibly 
26c90 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  even a NULL poin
26ca0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ter..**.** The s
26cb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
26cc0 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20  tes16() routine 
26cd0 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71  is similar to sq
26ce0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
26cf0 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76  es().** but leav
26d00 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  es the result in
26d10 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
26d20 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73  e byte order ins
26d30 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 20 20  tead of UTF-8.  
26d40 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74 65 72  .** The zero ter
26d50 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69  minator is not i
26d60 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20  ncluded in this 
26d70 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  count..**.** The
26d80 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
26d90 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
26da0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
26db0 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
26dc0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
26dd0 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e  ] object.  An un
26de0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
26df0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a  3_value object.*
26e00 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  * may only be us
26e10 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ed with [sqlite3
26e20 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
26e30 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
26e40 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
26e50 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
26e60 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
26e70 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
26e80 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
26e90 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
26ea0 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
26eb0 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
26ec0 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
26ed0 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
26ee0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
26ef0 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69  ue_int()], [sqli
26f00 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
26f10 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ], or [sqlite3_v
26f20 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 0a 2a  alue_bytes()],.*
26f30 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
26f40 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
26f50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
26f60 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74  utines attempt t
26f70 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
26f80 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70  lue where approp
26f90 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  riate.  For.** e
26fa0 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
26fb0 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
26fc0 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
26fd0 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
26fe0 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
26ff0 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
27000 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
27010 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 64 6f  internally to do
27020 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 0a   the conversion.
27030 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
27040 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  .  The following
27050 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
27060 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 74  he conversions t
27070 68 61 74 0a 2a 2a 20 61 72 65 20 61 70 70 6c 69  hat.** are appli
27080 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
27090 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
270a0 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
270b0 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
270c0 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
270d0 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
270e0 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
270f0 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
27100 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
27110 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
27120 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
27130 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
27140 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
27150 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
27160 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
27170 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
27180 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
27190 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
271a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
271b0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
271c0 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
271d0 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
271e0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
271f0 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
27200 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
27210 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
27220 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
27230 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
27240 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
27250 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
27260 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
27270 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
27280 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
27290 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
272a0 20 66 6f 72 20 49 4e 54 45 47 45 52 2d 3e 54 45   for INTEGER->TE
272b0 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
272c0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
272d0 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
272e0 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74  ert from float t
272f0 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  o integer.** <tr
27300 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
27310 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
27320 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
27330 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
27340 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
27350 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
27360 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
27370 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20   FLOAT->TEXT.** 
27380 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
27390 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
273a0 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29   <td> Use atoi()
273b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
273c0 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
273d0 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  T    <td> Use at
273e0 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
273f0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
27400 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
27410 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
27420 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
27430 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
27440 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
27450 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29   then use atoi()
27460 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
27470 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
27480 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
27490 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
274a0 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
274b0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
274c0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
274d0 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
274e0 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
274f0 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
27500 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  * </blockquote>.
27510 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
27520 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65  above makes refe
27530 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72  rence to standar
27540 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63  d C library func
27550 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20  tions atoi().** 
27560 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c  and atof().  SQL
27570 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61  ite does not rea
27580 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75  lly use these fu
27590 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73  nctions.  It has
275a0 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69   its.** own equi
275b0 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20  valent internal 
275c0 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61  routines.  The a
275d0 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29  toi() and atof()
275e0 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73   names are.** us
275f0 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20  ed in the table 
27600 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20  for brevity and 
27610 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65  because they are
27620 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73   familiar to mos
27630 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65  t.** C programme
27640 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  rs..**.** Note t
27650 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
27660 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
27670 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
27680 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
27690 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
276a0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
276b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
276c0 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
276d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
276e0 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
276f0 6e 76 61 6c 69 64 61 74 65 64 2e 20 0a 2a 2a 20  nvalidated. .** 
27700 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  Type conversions
27710 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76   and pointer inv
27720 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74  alidations might
27730 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
27740 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73   following cases
27750 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
27760 3c 6c 69 3e 3c 70 3e 20 20 54 68 65 20 69 6e 69  <li><p>  The ini
27770 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
27780 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
27790 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
277a0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72   .**          or
277b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
277c0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
277d0 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
277e0 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
277f0 20 20 20 20 20 20 20 20 20 6e 65 65 64 20 74 6f           need to
27800 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65   be added to the
27810 20 73 74 72 69 6e 67 2e 3c 2f 70 3e 3c 2f 6c 69   string.</p></li
27820 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20  >.**.** <li><p> 
27830 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
27840 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
27850 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
27860 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
27870 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  or.**          s
27880 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
27890 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
278a0 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
278b0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
278c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
278d0 55 54 46 2d 31 36 2e 3c 2f 70 3e 3c 2f 6c 69 3e  UTF-16.</p></li>
278e0 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 3c 70 3e 20 20  .**.** <li><p>  
278f0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
27900 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
27910 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
27920 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
27930 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 71 6c  .**          sql
27940 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
27950 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
27960 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
27970 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
27980 20 20 20 20 20 20 20 20 20 74 6f 20 55 54 46 2d           to UTF-
27990 38 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  8.</p></li>.** <
279a0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65  /ul>.**.** Conve
279b0 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
279c0 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
279d0 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
279e0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
279f0 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
27a00 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
27a10 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
27a20 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
27a30 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
27a40 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
27a50 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69  rior pointer poi
27a60 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65  nts to will have
27a70 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
27a80 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
27a90 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
27aa0 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
27ab0 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
27ac0 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
27ad0 65 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70  e it is.** not p
27ae0 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
27af0 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
27b00 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
27b10 76 61 6c 69 64 61 74 65 64 2e 20 20 0a 2a 2a 0a  validated.  .**.
27b20 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e  ** The safest an
27b30 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
27b40 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
27b50 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
27b60 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
27b70 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
27b80 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
27b90 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71   <ul>.**  <li>sq
27ba0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
27bb0 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  t() followed by 
27bc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
27bd0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
27be0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
27bf0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77  mn_blob() follow
27c00 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
27c10 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
27c20 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
27c30 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
27c40 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
27c50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
27c60 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  es16()</li>.**  
27c70 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f  </ul>.**.** In o
27c80 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20  ther words, you 
27c90 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69  should call sqli
27ca0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
27cb0 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
27cc0 6e 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 6f 72 20  n_blob(),.** or 
27cd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
27ce0 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f  ext16() first to
27cf0 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c   force the resul
27d00 74 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  t into the desir
27d10 65 64 0a 2a 2a 20 66 6f 72 6d 61 74 2c 20 74 68  ed.** format, th
27d20 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  en invoke sqlite
27d30 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
27d40 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
27d50 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 0a  mn_bytes16() to.
27d60 2a 2a 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65  ** find the size
27d70 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20   of the result. 
27d80 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   Do not mix call
27d90 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
27da0 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20  mn_text() or.** 
27db0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
27dc0 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73  lob() with calls
27dd0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
27de0 6d 6e 5f 62 79 74 65 73 31 36 28 29 2e 20 20 41  mn_bytes16().  A
27df0 6e 64 20 64 6f 20 6e 6f 74 0a 2a 2a 20 6d 69 78  nd do not.** mix
27e00 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
27e10 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
27e20 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  ) with calls to 
27e30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
27e40 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  ytes()..**.** Th
27e50 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
27e60 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
27e70 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
27e80 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
27e90 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
27ea0 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
27eb0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
27ec0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
27ed0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
27ee0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
27ef0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65   called.  The me
27f00 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20  mory space used 
27f10 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a  to hold strings.
27f20 2a 2a 20 61 6e 64 20 62 6c 6f 62 73 20 69 73 20  ** and blobs is 
27f30 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
27f40 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c  lly.  Do <b>not<
27f50 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  /b> pass the poi
27f60 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
27f70 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
27f80 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
27f90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
27fa0 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 20 0a 2a  )], etc. into .*
27fb0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
27fc0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d  )]..**.** If a m
27fd0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
27fe0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
27ff0 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74  ring the evaluat
28000 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ion of any.** of
28010 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
28020 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65   a default value
28030 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
28040 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
28050 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68  .** is either th
28060 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65  e integer 0, the
28070 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
28080 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61  number 0.0, or a
28090 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
280a0 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61  .  Subsequent ca
280b0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
280c0 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20  errcode()] will 
280d0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
280e0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
280f0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
28100 2a 20 7b 46 31 33 38 30 33 7d 20 54 68 65 20 5b  * {F13803} The [
28110 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
28120 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  lob(S,N)] interf
28130 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
28140 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
28150 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
28160 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
28170 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
28180 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
28190 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
281a0 5d 20 53 20 69 6e 74 6f 20 61 20 62 6c 6f 62 20  ] S into a blob 
281b0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
281c0 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70   a.**          p
281d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ointer to the co
281e0 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a  nverted value..*
281f0 2a 0a 2a 2a 20 7b 46 31 33 38 30 36 7d 20 54 68  *.** {F13806} Th
28200 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
28210 6e 5f 62 79 74 65 73 28 53 2c 4e 29 5d 20 69 6e  n_bytes(S,N)] in
28220 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
28230 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
28240 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
28250 69 6e 20 74 68 65 20 62 6c 6f 62 20 6f 72 20 73  in the blob or s
28260 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65  tring (exclusive
28270 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
28280 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61      zero termina
28290 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e  tor on the strin
282a0 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75  g) that was retu
282b0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20  rned by the.**  
282c0 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63          most rec
282d0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
282e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
282f0 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  (S,N)] or.**    
28300 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
28310 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d  olumn_text(S,N)]
28320 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 39 7d  ..**.** {F13809}
28330 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
28340 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 53 2c 4e  lumn_bytes16(S,N
28350 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
28360 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
28370 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62       number of b
28380 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
28390 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66  ng (exclusive of
283a0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
283b0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
283c0 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20   on the string) 
283d0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
283e0 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
283f0 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74       most recent
28400 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
28410 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
28420 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  S,N)]..**.** {F1
28430 33 38 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  3812} The [sqlit
28440 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
28450 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
28460 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
28470 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f            Nth co
28480 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
28490 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
284a0 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a  esult set for.**
284b0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
284c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
284d0 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67   into a floating
284e0 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e 64   point value and
284f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
28500 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  urns a copy of t
28510 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  hat value..**.**
28520 20 7b 46 31 33 38 31 35 7d 20 54 68 65 20 5b 73   {F13815} The [s
28530 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
28540 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  t(S,N)] interfac
28550 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
28560 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63  *          Nth c
28570 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
28580 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
28590 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a  result set for.*
285a0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
285b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
285c0 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20  S into a 64-bit 
285d0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
285e0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  nd.**          r
285f0 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72  eturns the lower
28600 20 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 74   32 bits of that
28610 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
28620 7b 46 31 33 38 31 38 7d 20 54 68 65 20 5b 73 71  {F13818} The [sq
28630 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
28640 36 34 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  64(S,N)] interfa
28650 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
28660 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
28670 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
28680 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
28690 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
286a0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
286b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
286c0 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74   S into a 64-bit
286d0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
286e0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
286f0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
28700 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a  f that integer..
28710 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 31 7d 20 54  **.** {F13821} T
28720 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
28730 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20 69 6e  mn_text(S,N)] in
28740 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
28750 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
28760 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
28770 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
28780 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
28790 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
287a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
287b0 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 7a  ment] S into a z
287c0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
287d0 54 46 2d 38 20 0a 2a 2a 20 20 20 20 20 20 20 20  TF-8 .**        
287e0 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74    string and ret
287f0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
28800 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
28810 2a 0a 2a 2a 20 7b 46 31 33 38 32 34 7d 20 54 68  *.** {F13824} Th
28820 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
28830 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 20 69  n_text16(S,N)] i
28840 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
28850 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
28860 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
28870 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
28880 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
28890 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
288a0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
288b0 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
288c0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
288d0 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20  2-byte.**       
288e0 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31     aligned UTF-1
288f0 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
28900 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
28910 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
28920 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
28930 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
28940 2a 2a 20 7b 46 31 33 38 32 37 7d 20 54 68 65 20  ** {F13827} The 
28950 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
28960 74 79 70 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  type(S,N)] inter
28970 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
28980 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20           one of 
28990 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b  [SQLITE_NULL], [
289a0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
289b0 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
289c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
289d0 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b  LITE_TEXT], or [
289e0 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20  SQLITE_BLOB] as 
289f0 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a  appropriate for.
28a00 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
28a10 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
28a20 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
28a30 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
28a40 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
28a50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28a60 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ent] S..**.** {F
28a70 31 33 38 33 30 7d 20 54 68 65 20 5b 73 71 6c 69  13830} The [sqli
28a80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
28a90 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
28aa0 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20   returns a.**   
28ab0 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74         pointer t
28ac0 6f 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65  o an [unprotecte
28ad0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
28ae0 20 6f 62 6a 65 63 74 20 66 6f 72 20 74 68 65 0a   object for the.
28af0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
28b00 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
28b10 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
28b20 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
28b30 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
28b40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28b50 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69   S..*/.const voi
28b60 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
28b70 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
28b80 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
28b90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
28ba0 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
28bb0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
28bc0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
28bd0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
28be0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
28bf0 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20  t iCol);.double 
28c00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
28c10 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
28c20 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
28c30 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
28c40 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
28c50 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
28c60 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
28c70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
28c80 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
28c90 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
28ca0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
28cb0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
28cc0 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
28cd0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
28ce0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
28cf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
28d00 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
28d10 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
28d20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28d30 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
28d40 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
28d50 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
28d60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
28d70 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
28d80 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a  , int iCol);../*
28d90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
28da0 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64  stroy A Prepared
28db0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
28dc0 74 20 7b 46 31 33 33 30 30 7d 0a 2a 2a 0a 2a 2a  t {F13300}.**.**
28dd0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e   The sqlite3_fin
28de0 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
28df0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65   is called to de
28e00 6c 65 74 65 20 61 20 0a 2a 2a 20 5b 70 72 65 70  lete a .** [prep
28e10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
28e20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
28e30 74 20 77 61 73 0a 2a 2a 20 65 78 65 63 75 74 65  t was.** execute
28e40 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  d successfully, 
28e50 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20  or not executed 
28e60 61 74 20 61 6c 6c 2c 20 74 68 65 6e 20 53 51 4c  at all, then SQL
28e70 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e  ITE_OK is return
28e80 65 64 2e 0a 2a 2a 20 49 66 20 65 78 65 63 75 74  ed..** If execut
28e90 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
28ea0 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e  ment failed then
28eb0 20 61 6e 20 0a 2a 2a 20 5b 65 72 72 6f 72 20 63   an .** [error c
28ec0 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  ode] or [extende
28ed0 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a  d error code].**
28ee0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 0a 2a   is returned. .*
28ef0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
28f00 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
28f10 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
28f20 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
28f30 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  n of the.** [pre
28f40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28f50 2e 20 20 49 66 20 74 68 65 20 76 69 72 74 75 61  .  If the virtua
28f60 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f  l machine has no
28f70 74 20 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  t .** completed 
28f80 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74  execution when t
28f90 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63  his routine is c
28fa0 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c  alled, that is l
28fb0 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ike.** encounter
28fc0 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  ing an error or 
28fd0 61 6e 20 69 6e 74 65 72 72 75 70 74 2e 20 20 28  an interrupt.  (
28fe0 53 65 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  See [sqlite3_int
28ff0 65 72 72 75 70 74 28 29 5d 2e 29 20 0a 2a 2a 20  errupt()].) .** 
29000 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74  Incomplete updat
29010 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64  es may be rolled
29020 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61   back and transa
29030 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c  ctions canceled,
29040 20 20 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20    .** depending 
29050 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74 61  on the circumsta
29060 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 20 0a 2a  nces, and the .*
29070 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 72  * [error code] r
29080 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20  eturned will be 
29090 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a  [SQLITE_ABORT]..
290a0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
290b0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30 32 7d  :.**.** {F11302}
290c0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   The [sqlite3_fi
290d0 6e 61 6c 69 7a 65 28 53 29 5d 20 69 6e 74 65 72  nalize(S)] inter
290e0 66 61 63 65 20 64 65 73 74 72 6f 79 73 20 74 68  face destroys th
290f0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
29100 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29110 74 5d 20 53 20 61 6e 64 20 72 65 6c 65 61 73 65  t] S and release
29120 73 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  s all.**        
29130 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20 66 69 6c    memory and fil
29140 65 20 72 65 73 6f 75 72 63 65 73 20 68 65 6c 64  e resources held
29150 20 62 79 20 74 68 61 74 20 6f 62 6a 65 63 74 2e   by that object.
29160 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 30 34 7d 20  .**.** {F11304} 
29170 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
29180 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
29190 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
291a0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
291b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
291c0 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
291d0 20 61 6e 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20   an error,.**   
291e0 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c         then [sql
291f0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
29200 5d 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 73  ] returns that s
29210 61 6d 65 20 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e  ame error..*/.in
29220 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
29230 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
29240 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
29250 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
29260 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
29270 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46 31 33  ment Object {F13
29280 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  330}.**.** The s
29290 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66  qlite3_reset() f
292a0 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
292b0 64 20 74 6f 20 72 65 73 65 74 20 61 20 0a 2a 2a  d to reset a .**
292c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
292d0 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  ment] object..**
292e0 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
292f0 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
29300 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
29310 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20  ted..** Any SQL 
29320 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
29330 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
29340 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
29350 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
29360 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
29370 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
29380 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
29390 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
293a0 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
293b0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
293c0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
293d0 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ndings..**.** {F
293e0 31 31 33 33 32 7d 20 54 68 65 20 5b 73 71 6c 69  11332} The [sqli
293f0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
29400 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74  terface resets t
29410 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
29420 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20  tement] S.**    
29430 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20 74 68        back to th
29440 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69  e beginning of i
29450 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  ts program..**.*
29460 2a 20 7b 46 31 31 33 33 34 7d 20 49 66 20 74 68  * {F11334} If th
29470 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
29480 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
29490 74 65 70 28 53 29 5d 20 66 6f 72 20 0a 2a 2a 20  tep(S)] for .** 
294a0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
294b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
294c0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
294d0 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _ROW] or [SQLITE
294e0 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20 20  _DONE],.**      
294f0 20 20 20 20 6f 72 20 69 66 20 5b 73 71 6c 69 74      or if [sqlit
29500 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
29510 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65  never before bee
29520 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a  n called on S,.*
29530 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
29540 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
29550 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
29560 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  TE_OK]..**.** {F
29570 31 31 33 33 36 7d 20 49 66 20 74 68 65 20 6d 6f  11336} If the mo
29580 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
29590 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
295a0 53 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  S)] for.**      
295b0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
295c0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
295d0 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
295e0 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
295f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
29600 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  )] returns an ap
29610 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
29620 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46   code]..**.** {F
29630 31 31 33 33 38 7d 20 54 68 65 20 5b 73 71 6c 69  11338} The [sqli
29640 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
29650 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
29660 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
29670 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  es.**          o
29680 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62  f any [sqlite3_b
29690 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67  ind_blob|binding
296a0 73 5d 20 6f 6e 20 5b 70 72 65 70 61 72 65 64 20  s] on [prepared 
296b0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
296c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73  .int sqlite3_res
296d0 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  et(sqlite3_stmt 
296e0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
296f0 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65  CAPI3REF: Create
29700 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c   Or Redefine SQL
29710 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 36 31   Functions {F161
29720 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00}.** KEYWORDS:
29730 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   {function creat
29740 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a  ion routines}.**
29750 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
29760 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
29770 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a  SQL function}.**
29780 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
29790 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
297a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  SQL functions}.*
297b0 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f 20 66  *.** These two f
297c0 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63  unctions (collec
297d0 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 0a  tively known as.
297e0 2a 2a 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  ** "function cre
297f0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
29800 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
29810 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
29820 72 20 61 67 67 72 65 67 61 74 65 73 0a 2a 2a 20  r aggregates.** 
29830 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
29840 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 65  he behavior of e
29850 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
29860 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
29870 74 65 73 2e 20 20 54 68 65 0a 2a 2a 20 64 69 66  tes.  The.** dif
29880 66 65 72 65 6e 63 65 20 6f 6e 6c 79 20 62 65 74  ference only bet
29890 77 65 65 6e 20 74 68 65 20 74 77 6f 20 69 73 20  ween the two is 
298a0 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
298b0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 0a 2a  parameter, the.*
298c0 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73  * name of the (s
298d0 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20  calar) function 
298e0 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 69 73  or aggregate, is
298f0 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d   encoded in UTF-
29900 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
29910 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
29920 28 29 20 61 6e 64 20 55 54 46 2d 31 36 20 66 6f  () and UTF-16 fo
29930 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
29940 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a  _function16()..*
29950 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
29960 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
29970 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
29980 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
29990 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
299a0 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
299b0 64 2e 20 20 49 66 20 61 20 73 69 6e 67 6c 65 0a  d.  If a single.
299c0 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20  ** program uses 
299d0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 5b 64  more than one [d
299e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
299f0 6f 6e 5d 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20  on] internally, 
29a00 74 68 65 6e 20 53 51 4c 0a 2a 2a 20 66 75 6e 63  then SQL.** func
29a10 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
29a20 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ded individually
29a30 20 74 6f 20 65 61 63 68 20 5b 64 61 74 61 62 61   to each [databa
29a40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
29a50 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
29a60 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
29a70 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
29a80 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
29a90 20 63 72 65 61 74 65 64 0a 2a 2a 20 6f 72 20 72   created.** or r
29aa0 65 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  edefined..** The
29ab0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
29ac0 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
29ad0 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 78 63  o 255 bytes, exc
29ae0 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 0a 2a  lusive of the .*
29af0 2a 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  * zero-terminato
29b00 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  r.  Note that th
29b10 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69  e name length li
29b20 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c  mit is in bytes,
29b30 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65   not.** characte
29b40 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74  rs.  Any attempt
29b50 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
29b60 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
29b70 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
29b80 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 53 51   result in an SQ
29b90 4c 49 54 45 5f 45 52 52 4f 52 20 65 72 72 6f 72  LITE_ERROR error
29ba0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72  ..**.** The thir
29bb0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
29bc0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
29bd0 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
29be0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
29bf0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
29c00 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 72 61  es. If this para
29c10 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76  meter is negativ
29c20 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  e, then the SQL 
29c30 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
29c40 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
29c50 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
29c60 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
29c70 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
29c80 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c  meter, eTextRep,
29c90 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 20   specifies what 
29ca0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
29cb0 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
29cc0 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
29cd0 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
29ce0 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
29cf0 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63  s.  Any SQL func
29d00 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
29d10 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62  ion should be ab
29d20 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f  le to work.** wo
29d30 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55  rk with UTF-8, U
29d40 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d  TF-16le, or UTF-
29d50 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20  16be.  But some 
29d60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
29d70 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65  may be.** more e
29d80 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e  fficient with on
29d90 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20  e encoding than 
29da0 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73 20  another.  It is 
29db0 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e  allowed to.** in
29dc0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  voke sqlite3_cre
29dd0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f  ate_function() o
29de0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
29df0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75  _function16() mu
29e00 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
29e10 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75  with the same fu
29e20 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20  nction but with 
29e30 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73  different values
29e40 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a   of eTextRep..**
29e50 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69   When multiple i
29e60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
29e70 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
29e80 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
29e90 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
29ea0 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
29eb0 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
29ec0 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
29ed0 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
29ee0 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73  ..** If there is
29ef0 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69   only a single i
29f00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
29f10 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  ich does not car
29f20 65 20 77 68 61 74 0a 2a 2a 20 74 65 78 74 20 65  e what.** text e
29f30 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c  ncoding is used,
29f40 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
29f50 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
29f60 20 62 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 41   be.** [SQLITE_A
29f70 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  NY]..**.** The f
29f80 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
29f90 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
29fa0 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
29fb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f  lementation.** o
29fc0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 63  f the function c
29fd0 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
29fe0 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
29ff0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2a000 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a  _user_data()]..*
2a010 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 68  *.** The seventh
2a020 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69 6e  , eighth and nin
2a030 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78  th parameters, x
2a040 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20  Func, xStep and 
2a050 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70  xFinal, are.** p
2a060 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e  ointers to C-lan
2a070 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20  guage functions 
2a080 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
2a090 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
2a0a0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
2a0b0 20 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75   A scalar SQL fu
2a0c0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
2a0d0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
2a0e0 6e 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 75 6e  n of.** the xFun
2a0f0 63 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c  c callback only,
2a100 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73   NULL pointers s
2a110 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20  hould be passed 
2a120 61 73 20 74 68 65 20 78 53 74 65 70 0a 2a 2a 20  as the xStep.** 
2a130 61 6e 64 20 78 46 69 6e 61 6c 20 70 61 72 61 6d  and xFinal param
2a140 65 74 65 72 73 2e 20 41 6e 20 61 67 67 72 65 67  eters. An aggreg
2a150 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
2a160 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
2a170 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f  lementation.** o
2a180 66 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  f xStep and xFin
2a190 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75  al and NULL shou
2a1a0 6c 64 20 62 65 20 70 61 73 73 65 64 20 66 6f 72  ld be passed for
2a1b0 20 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74   xFunc. To delet
2a1c0 65 20 61 6e 0a 2a 2a 20 65 78 69 73 74 69 6e 67  e an.** existing
2a1d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2a1e0 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73   aggregate, pass
2a1f0 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68   NULL for all th
2a200 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ree function.** 
2a210 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a  callbacks..**.**
2a220 20 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64   It is permitted
2a230 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c   to register mul
2a240 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
2a250 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2a260 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77  e.** functions w
2a270 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
2a280 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65  e but with eithe
2a290 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62  r differing numb
2a2a0 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65  ers of.** argume
2a2b0 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67  nts or differing
2a2c0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
2a2d0 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c 69  encodings.  SQLi
2a2e0 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
2a2f0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
2a300 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d  n most closely m
2a310 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69  atches the way i
2a320 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53  n which the.** S
2a330 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  QL function is u
2a340 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  sed..**.** INVAR
2a350 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
2a360 36 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  6103} The [sqlit
2a370 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2a380 6f 6e 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  on16()] interfac
2a390 65 20 62 65 68 61 76 65 73 20 65 78 61 63 74 6c  e behaves exactl
2a3a0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 69  y.**          li
2a3b0 6b 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ke [sqlite3_crea
2a3c0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 69  te_function()] i
2a3d0 6e 20 65 76 65 72 79 20 77 61 79 20 65 78 63 65  n every way exce
2a3e0 70 74 20 74 68 61 74 20 69 74 0a 2a 2a 20 20 20  pt that it.**   
2a3f0 20 20 20 20 20 20 20 69 6e 74 65 72 70 72 65 74         interpret
2a400 73 20 74 68 65 20 7a 46 75 6e 63 74 69 6f 6e 4e  s the zFunctionN
2a410 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 61 73 0a  ame argument as.
2a420 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
2a430 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
2a440 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
2a450 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  rder instead of 
2a460 61 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  as a.**         
2a470 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2a480 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46   UTF-8..**.** {F
2a490 31 36 31 30 36 7d 20 41 20 73 75 63 63 65 73 73  16106} A success
2a4a0 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
2a4b0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  f.**          th
2a4c0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2a4d0 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2a4e0 2c 45 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  ,E,...)] interfa
2a4f0 63 65 20 72 65 67 69 73 74 65 72 73 0a 2a 2a 20  ce registers.** 
2a500 20 20 20 20 20 20 20 20 20 6f 72 20 72 65 70 6c           or repl
2a510 61 63 65 73 20 63 61 6c 6c 62 61 63 6b 20 66 75  aces callback fu
2a520 6e 63 74 69 6f 6e 73 20 69 6e 20 5b 64 61 74 61  nctions in [data
2a530 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2a540 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75   D.**          u
2a550 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
2a560 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2a570 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20 4e  n named X with N
2a580 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20   parameters.**  
2a590 20 20 20 20 20 20 20 20 61 6e 64 20 68 61 76 69          and havi
2a5a0 6e 67 20 61 20 70 72 65 66 65 72 72 65 64 20 74  ng a preferred t
2a5b0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  ext encoding of 
2a5c0 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30 39  E..**.** {F16109
2a5d0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
2a5e0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2a5f0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2a600 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
2a610 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  ].**          re
2a620 70 6c 61 63 65 73 20 74 68 65 20 50 2c 20 46 2c  places the P, F,
2a630 20 53 2c 20 61 6e 64 20 4c 20 76 61 6c 75 65 73   S, and L values
2a640 20 66 72 6f 6d 20 61 6e 79 20 70 72 69 6f 72 20   from any prior 
2a650 63 61 6c 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20  calls with.**   
2a660 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20         the same 
2a670 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20 45 20 76  D, X, N, and E v
2a680 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  alues..**.** {F1
2a690 36 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  6112} The [sqlit
2a6a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2a6b0 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74  on(D,X,...)] int
2a6c0 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
2a6d0 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  h.**          a 
2a6e0 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b  return code of [
2a6f0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
2a700 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2a710 6e 20 6e 61 6d 65 20 58 20 69 73 0a 2a 2a 20 20  n name X is.**  
2a720 20 20 20 20 20 20 20 20 6c 6f 6e 67 65 72 20 74          longer t
2a730 68 61 6e 20 32 35 35 20 62 79 74 65 73 20 65 78  han 255 bytes ex
2a740 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a  clusive of the z
2a750 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
2a760 2a 2a 0a 2a 2a 20 7b 46 31 36 31 31 38 7d 20 45  **.** {F16118} E
2a770 69 74 68 65 72 20 46 20 6d 75 73 74 20 62 65 20  ither F must be 
2a780 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c  NULL and S and L
2a790 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f 72   are non-NULL or
2a7a0 20 65 6c 73 65 20 46 0a 2a 2a 20 20 20 20 20 20   else F.**      
2a7b0 20 20 20 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20      is non-NULL 
2a7c0 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65 20  and S and L are 
2a7d0 4e 55 4c 4c 2c 20 6f 74 68 65 72 77 69 73 65 0a  NULL, otherwise.
2a7e0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2a7f0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2a800 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  tion(D,X,N,E,P,F
2a810 2c 53 2c 4c 29 5d 20 72 65 74 75 72 6e 73 20 5b  ,S,L)] returns [
2a820 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 0a 2a  SQLITE_ERROR]..*
2a830 2a 0a 2a 2a 20 7b 46 31 36 31 32 31 7d 20 54 68  *.** {F16121} Th
2a840 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2a850 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 2e 2e 2e  e_function(D,...
2a860 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  )] interface fai
2a870 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20  ls with an.**   
2a880 20 20 20 20 20 20 20 65 72 72 6f 72 20 63 6f 64         error cod
2a890 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42 55 53  e of [SQLITE_BUS
2a8a0 59 5d 20 69 66 20 74 68 65 72 65 20 65 78 69 73  Y] if there exis
2a8b0 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  t [prepared stat
2a8c0 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20 20 20 20 20  ements].**      
2a8d0 20 20 20 20 61 73 73 6f 63 69 61 74 65 64 20 77      associated w
2a8e0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
2a8f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e  e connection] D.
2a900 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 34 7d 20  .**.** {F16124} 
2a910 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
2a920 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2a930 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  ,N,...)] interfa
2a940 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  ce fails with an
2a950 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72 72  .**          err
2a960 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  or code of [SQLI
2a970 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 70 61 72  TE_ERROR] if par
2a980 61 6d 65 74 65 72 20 4e 20 28 73 70 65 63 69 66  ameter N (specif
2a990 79 69 6e 67 20 74 68 65 20 6e 75 6d 62 65 72 0a  ying the number.
2a9a0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61  **          of a
2a9b0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
2a9c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  SQL function bei
2a9d0 6e 67 20 72 65 67 69 73 74 65 72 65 64 29 20 69  ng registered) i
2a9e0 73 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20 20  s less.**       
2a9f0 20 20 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72     than -1 or gr
2aa00 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 2e 0a  eater than 127..
2aa10 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 37 7d 20 57  **.** {F16127} W
2aa20 68 65 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67  hen N is non-neg
2aa30 61 74 69 76 65 2c 20 74 68 65 20 5b 73 71 6c 69  ative, the [sqli
2aa40 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2aa50 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a  ion(D,X,N,...)].
2aa60 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
2aa70 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61 6c  rface causes cal
2aa80 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76  lbacks to be inv
2aa90 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51 4c  oked for the SQL
2aaa0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
2aab0 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77 68        named X wh
2aac0 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  en the number of
2aad0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
2aae0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
2aaf0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78  s.**          ex
2ab00 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b  actly N..**.** {
2ab10 46 31 36 31 33 30 7d 20 57 68 65 6e 20 4e 20 69  F16130} When N i
2ab20 73 20 2d 31 2c 20 74 68 65 20 5b 73 71 6c 69 74  s -1, the [sqlit
2ab30 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2ab40 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a  on(D,X,N,...)].*
2ab50 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
2ab60 66 61 63 65 20 63 61 75 73 65 73 20 63 61 6c 6c  face causes call
2ab70 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f  backs to be invo
2ab80 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51 4c 20  ked for the SQL 
2ab90 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  function.**     
2aba0 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77 69 74       named X wit
2abb0 68 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  h any number of 
2abc0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
2abd0 20 7b 46 31 36 31 33 33 7d 20 57 68 65 6e 20 63   {F16133} When c
2abe0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2abf0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2ac00 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20  (D,X,N,...)].** 
2ac10 20 20 20 20 20 20 20 20 20 73 70 65 63 69 66 79           specify
2ac20 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
2ac30 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
2ac40 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58   same function X
2ac50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
2ac60 20 77 68 65 6e 20 6f 6e 65 20 69 6d 70 6c 65 6d   when one implem
2ac70 65 6e 74 61 74 69 6f 6e 20 68 61 73 20 4e 3e 3d  entation has N>=
2ac80 30 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  0 and the other 
2ac90 68 61 73 20 4e 3d 28 2d 31 29 0a 2a 2a 20 20 20  has N=(-1).**   
2aca0 20 20 20 20 20 20 20 74 68 65 20 69 6d 70 6c 65         the imple
2acb0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
2acc0 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20 69 73 20 70   non-zero N is p
2acd0 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  referred..**.** 
2ace0 7b 46 31 36 31 33 36 7d 20 57 68 65 6e 20 63 61  {F16136} When ca
2acf0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2ad00 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2ad10 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a  D,X,N,E,...)].**
2ad20 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69 66            specif
2ad30 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  y multiple imple
2ad40 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
2ad50 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2ad60 58 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  X with.**       
2ad70 20 20 20 74 68 65 20 73 61 6d 65 20 6e 75 6d 62     the same numb
2ad80 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2ad90 4e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  N but with diffe
2ada0 72 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  rent.**         
2adb0 20 65 6e 63 6f 64 69 6e 67 73 20 45 2c 20 74 68   encodings E, th
2adc0 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  en the implement
2add0 61 74 69 6f 6e 20 77 68 65 72 65 20 45 20 6d 61  ation where E ma
2ade0 74 63 68 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  tches the.**    
2adf0 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20 65        database e
2ae00 6e 63 6f 64 69 6e 67 20 69 73 20 70 72 65 66 65  ncoding is prefe
2ae10 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  rred..**.** {F16
2ae20 31 33 39 7d 20 46 6f 72 20 61 6e 20 61 67 67 72  139} For an aggr
2ae30 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2ae40 6f 6e 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  on created using
2ae50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2ae60 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2ae70 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
2ae80 30 2c 53 2c 4c 29 5d 20 74 68 65 20 66 69 6e 69  0,S,L)] the fini
2ae90 61 6c 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20  alizer.**       
2aea0 20 20 20 66 75 6e 63 74 69 6f 6e 20 4c 20 77 69     function L wi
2aeb0 6c 6c 20 61 6c 77 61 79 73 20 62 65 20 69 6e 76  ll always be inv
2aec0 6f 6b 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63  oked exactly onc
2aed0 65 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  e if the.**     
2aee0 20 20 20 20 20 73 74 65 70 20 66 75 6e 63 74 69       step functi
2aef0 6f 6e 20 53 20 69 73 20 63 61 6c 6c 65 64 20 6f  on S is called o
2af00 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
2af10 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 34 32 7d  ..**.** {F16142}
2af20 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
2af30 6f 6b 65 73 20 65 69 74 68 65 72 20 74 68 65 20  okes either the 
2af40 78 46 75 6e 63 20 6f 72 20 78 53 74 65 70 20 66  xFunc or xStep f
2af50 75 6e 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20  unction of.**   
2af60 20 20 20 20 20 20 20 61 6e 20 61 70 70 6c 69 63         an applic
2af70 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2af80 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
2af90 67 72 65 67 61 74 65 20 63 72 65 61 74 65 64 0a  gregate created.
2afa0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 5b  **          by [
2afb0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2afc0 75 6e 63 74 69 6f 6e 28 29 5d 20 6f 72 20 5b 73  unction()] or [s
2afd0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2afe0 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a 20  nction16()],.** 
2aff0 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68           then th
2b000 65 20 61 72 72 61 79 20 6f 66 20 5b 73 71 6c 69  e array of [sqli
2b010 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2b020 74 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ts passed as the
2b030 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 69  .**          thi
2b040 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65  rd parameter are
2b050 20 61 6c 77 61 79 73 20 5b 70 72 6f 74 65 63 74   always [protect
2b060 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2b070 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69 6e  ] objects..*/.in
2b080 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2b090 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
2b0a0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
2b0b0 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
2b0c0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
2b0d0 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
2b0e0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
2b0f0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
2b100 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2b110 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2b120 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2b130 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
2b140 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2b150 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2b160 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
2b170 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2b180 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
2b190 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2b1a0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
2b1b0 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  b,.  const void 
2b1c0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
2b1d0 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
2b1e0 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
2b1f0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
2b200 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
2b210 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2b220 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2b230 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
2b240 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2b250 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2b260 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2b270 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
2b280 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f  _context*).);../
2b290 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
2b2a0 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b 46  ext Encodings {F
2b2b0 31 30 32 36 37 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  10267}.**.** The
2b2c0 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  se constant defi
2b2d0 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
2b2e0 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20   that represent 
2b2f0 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74  the various.** t
2b300 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75  ext encodings su
2b310 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
2b320 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
2b330 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20  LITE_UTF8       
2b340 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
2b350 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
2b360 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2b370 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20  LITE_UTF16BE    
2b380 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
2b390 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
2b3a0 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
2b3b0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2b3c0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
2b3d0 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
2b3e0 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74     5    /* sqlit
2b3f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2b400 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  on only */.#defi
2b410 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  ne SQLITE_UTF16_
2b420 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a  ALIGNED  8    /*
2b430 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2b440 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a  collation only *
2b450 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
2b460 46 3a 20 4f 62 73 6f 6c 65 74 65 20 46 75 6e 63  F: Obsolete Func
2b470 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
2b480 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
2b490 61 6c 6c 20 6e 6f 77 20 6f 62 73 6f 6c 65 74 65  all now obsolete
2b4a0 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
2b4b0 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
2b4c0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
2b4d0 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
2b4e0 64 65 2c 20 77 65 20 63 6f 6e 74 69 6e 75 65 20  de, we continue 
2b4f0 74 6f 20 73 75 70 70 6f 72 74 0a 2a 2a 20 74 68  to support.** th
2b500 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
2b510 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 64 65 76  However, new dev
2b520 65 6c 6f 70 6d 65 6e 74 20 70 72 6f 6a 65 63 74  elopment project
2b530 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a  s should avoid.*
2b540 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  * the use of the
2b550 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  se functions.  T
2b560 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65  o help encourage
2b570 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64   people to avoid
2b580 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20  .** using these 
2b590 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72  functions, we ar
2b5a0 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74  e not going to t
2b5b0 65 6c 6c 20 79 6f 75 20 77 61 6e 74 20 74 68 65  ell you want the
2b5c0 79 20 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  y do..*/.int sql
2b5d0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2b5e0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ount(sqlite3_con
2b5f0 74 65 78 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  text*);.int sqli
2b600 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
2b610 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20  te3_stmt*);.int 
2b620 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
2b630 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
2b640 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
2b650 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c  _stmt*);.int sql
2b660 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f  ite3_global_reco
2b670 76 65 72 28 76 6f 69 64 29 3b 0a 76 6f 69 64 20  ver(void);.void 
2b680 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
2b690 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 69 6e  leanup(void);.in
2b6a0 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  t sqlite3_memory
2b6b0 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76  _alarm(void(*)(v
2b6c0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
2b6d0 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71  64,int),void*,sq
2b6e0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f  lite3_int64);../
2b6f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2b700 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e  btaining SQL Fun
2b710 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20  ction Parameter 
2b720 56 61 6c 75 65 73 20 7b 46 31 35 31 30 30 7d 0a  Values {F15100}.
2b730 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
2b740 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
2b750 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
2b760 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
2b770 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
2b780 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
2b790 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
2b7a0 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
2b7b0 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
2b7c0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
2b7d0 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
2b7e0 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
2b7f0 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
2b800 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
2b810 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
2b820 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
2b830 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2b840 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
2b850 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2b860 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
2b870 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
2b880 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
2b890 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
2b8a0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
2b8b0 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d  ** The 4th param
2b8c0 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
2b8d0 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
2b8e0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
2b8f0 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
2b900 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2b910 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
2b920 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
2b930 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
2b940 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
2b950 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
2b960 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
2b970 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
2b980 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
2b990 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
2b9a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2b9b0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
2b9c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
2b9d0 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
2b9e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2b9f0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
2ba00 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
2ba10 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
2ba20 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
2ba30 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2ba40 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
2ba50 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
2ba60 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
2ba70 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2ba80 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c  ines work just l
2ba90 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ike the correspo
2baa0 6e 64 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  nding .** [sqlit
2bab0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 20 7c  e3_column_blob |
2bac0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bad0 2a 20 72 6f 75 74 69 6e 65 73 5d 20 65 78 63 65  * routines] exce
2bae0 70 74 20 74 68 61 74 20 0a 2a 2a 20 74 68 65 73  pt that .** thes
2baf0 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20  e routines take 
2bb00 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63  a single [protec
2bb10 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2bb20 65 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65  e] object pointe
2bb30 72 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66 20  r.** instead of 
2bb40 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  a [sqlite3_stmt*
2bb50 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e  ] pointer and an
2bb60 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20   integer column 
2bb70 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  number..**.** Th
2bb80 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
2bb90 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
2bba0 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
2bbb0 46 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  F16 string.** in
2bbc0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
2bbd0 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
2bbe0 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65  st machine.  The
2bbf0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2bc00 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
2bc10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2bc20 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
2bc30 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
2bc40 55 54 46 31 36 20 73 74 72 69 6e 67 73 20 61 73  UTF16 strings as
2bc50 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
2bc60 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
2bc70 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
2bc80 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
2bc90 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
2bca0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
2bcb0 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
2bcc0 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
2bcd0 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
2bce0 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
2bcf0 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
2bd00 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
2bd10 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
2bd20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
2bd30 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
2bd40 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
2bd50 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
2bd60 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
2bd70 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
2bd80 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64  in other.** word
2bd90 73 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  s if the value i
2bda0 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20  s a string that 
2bdb0 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d  looks like a num
2bdc0 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ber).** then the
2bdd0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 64   conversion is d
2bde0 6f 6e 65 2e 20 20 4f 74 68 65 72 77 69 73 65 20  one.  Otherwise 
2bdf0 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  no conversion oc
2be00 63 75 72 73 2e 20 20 54 68 65 20 0a 2a 2a 20 5b  curs.  The .** [
2be10 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
2be20 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
2be30 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
2be40 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  eturned..**.** P
2be50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63  lease pay partic
2be60 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74  ular attention t
2be70 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20  o the fact that 
2be80 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
2be90 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
2bea0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
2beb0 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
2bec0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2bed0 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2bee0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2bef0 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
2bf00 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
2bf10 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
2bf20 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
2bf30 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
2bf40 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
2bf50 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
2bf60 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
2bf70 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
2bf80 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 20 20 0a  ue_text16()].  .
2bf90 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2bfa0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
2bfb0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
2bfc0 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
2bfd0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2bfe0 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
2bff0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2c000 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
2c010 2a 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  *.**.** INVARIAN
2c020 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30  TS:.**.** {F1510
2c030 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
2c040 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 69  value_blob(V)] i
2c050 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2c060 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2c070 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2c080 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2c090 63 74 20 56 20 69 6e 74 6f 20 61 20 62 6c 6f 62  ct V into a blob
2c0a0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
2c0b0 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
2c0c0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63  pointer to the c
2c0d0 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a  onverted value..
2c0e0 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 36 7d 20 54  **.** {F15106} T
2c0f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2c100 65 5f 62 79 74 65 73 28 56 29 5d 20 69 6e 74 65  e_bytes(V)] inte
2c110 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
2c120 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
2c130 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2c140 20 74 68 65 20 62 6c 6f 62 20 6f 72 20 73 74 72   the blob or str
2c150 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f  ing (exclusive o
2c160 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2c170 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f    zero terminato
2c180 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29  r on the string)
2c190 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
2c1a0 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
2c1b0 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e        most recen
2c1c0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2c1d0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29  e3_value_blob(V)
2c1e0 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
2c1f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2c200 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20  text(V)]..**.** 
2c210 7b 46 31 35 31 30 39 7d 20 54 68 65 20 5b 73 71  {F15109} The [sq
2c220 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2c230 73 31 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63  s16(V)] interfac
2c240 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
2c250 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
2c260 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2c270 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69   string (exclusi
2c280 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  ve of the.**    
2c290 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69        zero termi
2c2a0 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72  nator on the str
2c2b0 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65  ing) that was re
2c2c0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
2c2d0 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72            most r
2c2e0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2c2f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2c300 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20 20 20 20  t16(V)],.**     
2c310 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61       [sqlite3_va
2c320 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d  lue_text16be(V)]
2c330 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  , or [sqlite3_va
2c340 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d  lue_text16le(V)]
2c350 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31 32 7d  ..**.** {F15112}
2c360 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2c370 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29 5d 20 69  lue_double(V)] i
2c380 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2c390 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2c3a0 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2c3b0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2c3c0 63 74 20 56 20 69 6e 74 6f 20 61 20 66 6c 6f 61  ct V into a floa
2c3d0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
2c3e0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
2c3f0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
2c400 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a  of that value..*
2c410 2a 0a 2a 2a 20 7b 46 31 35 31 31 35 7d 20 54 68  *.** {F15115} Th
2c420 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2c430 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65 72 66 61  _int(V)] interfa
2c440 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2c450 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f  **          [pro
2c460 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2c470 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69  alue] object V i
2c480 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67  nto a 64-bit sig
2c490 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a  ned integer and.
2c4a0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
2c4b0 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32  rns the lower 32
2c4c0 20 62 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e   bits of that in
2c4d0 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  teger..**.** {F1
2c4e0 35 31 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74  5118} The [sqlit
2c4f0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 56  e3_value_int64(V
2c500 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2c510 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
2c520 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
2c530 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2c540 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
2c550 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
2c560 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20  teger and.**    
2c570 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
2c580 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74  copy of that int
2c590 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  eger..**.** {F15
2c5a0 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  121} The [sqlite
2c5b0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d  3_value_text(V)]
2c5c0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2c5d0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2c5e0 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
2c5f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2c600 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65  ject V into a ze
2c610 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
2c620 46 2d 38 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  F-8 .**         
2c630 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2c640 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2c650 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2c660 0a 2a 2a 20 7b 46 31 35 31 32 34 7d 20 54 68 65  .** {F15124} The
2c670 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2c680 74 65 78 74 31 36 28 56 29 5d 20 69 6e 74 65 72  text16(V)] inter
2c690 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2c6a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2c6b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2c6c0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2c6d0 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72   into a zero-ter
2c6e0 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a  minated 2-byte.*
2c6f0 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e  *          align
2c700 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  ed UTF-16 native
2c710 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20   byte order.**  
2c720 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61          string a
2c730 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
2c740 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72  nter to that str
2c750 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31  ing..**.** {F151
2c760 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  27} The [sqlite3
2c770 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
2c780 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
2c790 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2c7a0 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
2c7b0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2c7c0 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
2c7d0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2c7e0 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20   2-byte.**      
2c7f0 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d      aligned UTF-
2c800 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a  16 big-endian.**
2c810 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
2c820 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
2c830 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
2c840 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tring..**.** {F1
2c850 35 31 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74  5130} The [sqlit
2c860 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
2c870 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(V)] interface 
2c880 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2c890 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
2c8a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2c8b0 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
2c8c0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2c8d0 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20  ed 2-byte.**    
2c8e0 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54        aligned UT
2c8f0 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69  F-16 little-endi
2c900 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  an.**          s
2c910 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2c920 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2c930 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  hat string..**.*
2c940 2a 20 7b 46 31 35 31 33 33 7d 20 54 68 65 20 5b  * {F15133} The [
2c950 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
2c960 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  pe(V)] interface
2c970 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
2c980 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c       one of [SQL
2c990 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49  ITE_NULL], [SQLI
2c9a0 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51  TE_INTEGER], [SQ
2c9b0 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20  LITE_FLOAT],.** 
2c9c0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
2c9d0 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49  _TEXT], or [SQLI
2c9e0 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72  TE_BLOB] as appr
2c9f0 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20  opriate for.**  
2ca00 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c          the [sql
2ca10 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2ca20 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  ct V..**.** {F15
2ca30 31 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  136} The [sqlite
2ca40 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
2ca50 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61  type(V)] interfa
2ca60 63 65 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 20  ce converts.**  
2ca70 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 6f          the [pro
2ca80 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2ca90 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69  alue] object V i
2caa0 6e 74 6f 20 65 69 74 68 65 72 20 61 6e 20 69 6e  nto either an in
2cab0 74 65 67 65 72 20 6f 72 0a 2a 2a 20 20 20 20 20  teger or.**     
2cac0 20 20 20 20 20 61 20 66 6c 6f 61 74 69 6e 67 20       a floating 
2cad0 70 6f 69 6e 74 20 76 61 6c 75 65 20 69 66 20 69  point value if i
2cae0 74 20 63 61 6e 20 64 6f 20 73 6f 20 77 69 74 68  t can do so with
2caf0 6f 75 74 20 6c 6f 73 73 20 6f 66 0a 2a 2a 20 20  out loss of.**  
2cb00 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61 74          informat
2cb10 69 6f 6e 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ion, and returns
2cb20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2cb30 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  NULL],.**       
2cb40 20 20 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47     [SQLITE_INTEG
2cb50 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ER], [SQLITE_FLO
2cb60 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
2cb70 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  T], or.**       
2cb80 20 20 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d     [SQLITE_BLOB]
2cb90 20 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20   as appropriate 
2cba0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
2cbb0 74 68 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73  the [protected s
2cbc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2cbd0 6a 65 63 74 20 56 20 61 66 74 65 72 20 74 68 65  ject V after the
2cbe0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 74 74 65   conversion atte
2cbf0 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  mpt..*/.const vo
2cc00 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
2cc10 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
2cc20 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2cc30 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2cc40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2cc50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
2cc60 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  ue_bytes16(sqlit
2cc70 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62  e3_value*);.doub
2cc80 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le sqlite3_value
2cc90 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2cca0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2ccb0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
2ccc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2ccd0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
2cce0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
2ccf0 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
2cd00 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
2cd10 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
2cd20 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74  value_text(sqlit
2cd30 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
2cd40 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2cd50 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c  value_text16(sql
2cd60 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
2cd70 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2cd80 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
2cd90 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2cda0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2cdb0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2cdc0 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16be(sqlite3_val
2cdd0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2cde0 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c  3_value_type(sql
2cdf0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2ce00 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2ce10 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
2ce20 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
2ce30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2ce40 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20  btain Aggregate 
2ce50 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
2ce60 20 7b 46 31 36 32 31 30 7d 0a 2a 2a 0a 2a 2a 20   {F16210}.**.** 
2ce70 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
2ce80 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74 65 20  on of aggregate 
2ce90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  SQL functions us
2cea0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
2ceb0 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20  o allocate.** a 
2cec0 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 73 74  structure for st
2ced0 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
2cee0 65 2e 20 20 0a 2a 2a 20 54 68 65 20 66 69 72 73  e.  .** The firs
2cef0 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74  t time the sqlit
2cf00 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2cf10 74 65 78 74 28 29 20 72 6f 75 74 69 6e 65 20 69  text() routine i
2cf20 73 0a 2a 2a 20 69 73 20 63 61 6c 6c 65 64 20 66  s.** is called f
2cf30 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
2cf40 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c 69 74  aggregate, SQLit
2cf50 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74  e allocates nByt
2cf60 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  es of memory.** 
2cf70 7a 65 72 6f 73 20 74 68 61 74 20 6d 65 6d 6f 72  zeros that memor
2cf80 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  y, and returns a
2cf90 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 0a   pointer to it..
2cfa0 2a 2a 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64  ** On second and
2cfb0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
2cfc0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67  s to sqlite3_agg
2cfd0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2cfe0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
2cff0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
2d000 69 6f 6e 20 69 6e 64 65 78 2c 20 74 68 65 20 73  ion index, the s
2d010 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65  ame buffer is re
2d020 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 69  turned..** The i
2d030 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
2d040 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74   of the aggregat
2d050 65 20 63 61 6e 20 75 73 65 20 74 68 65 20 72 65  e can use the re
2d060 74 75 72 6e 65 64 20 62 75 66 66 65 72 20 74 6f  turned buffer to
2d070 20 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74 61   accumulate data
2d080 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 61  ..**.** SQLite a
2d090 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
2d0a0 65 73 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  es the allocated
2d0b0 20 62 75 66 66 65 72 20 77 68 65 6e 20 74 68 65   buffer when the
2d0c0 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 75   aggregate.** qu
2d0d0 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a  ery concludes..*
2d0e0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
2d0f0 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
2d100 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
2d110 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
2d120 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
2d130 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
2d140 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  at is the first.
2d150 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
2d160 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  the callback rou
2d170 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
2d180 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
2d190 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a  te.** function..
2d1a0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2d1b0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
2d1c0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2d1d0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
2d1e0 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
2d1f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
2d200 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   running..**.** 
2d210 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2d220 2a 20 7b 46 31 36 32 31 31 7d 20 54 68 65 20 66  * {F16211} The f
2d230 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  irst invocation 
2d240 6f 66 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  of [sqlite3_aggr
2d250 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
2d260 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  N)] for.**      
2d270 20 20 20 20 61 20 70 61 72 74 69 63 75 6c 61 72      a particular
2d280 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61 6e 20   instance of an 
2d290 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
2d2a0 6f 6e 20 28 66 6f 72 20 61 20 70 61 72 74 69 63  on (for a partic
2d2b0 75 6c 61 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ular.**         
2d2c0 20 63 6f 6e 74 65 78 74 20 43 29 20 63 61 75 73   context C) caus
2d2d0 65 73 20 53 51 4c 69 74 65 20 74 6f 20 61 6c 6c  es SQLite to all
2d2e0 6f 63 61 74 69 6f 6e 20 4e 20 62 79 74 65 73 20  ocation N bytes 
2d2f0 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 20 20  of memory,.**   
2d300 20 20 20 20 20 20 20 7a 65 72 6f 20 74 68 61 74         zero that
2d310 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74   memory, and ret
2d320 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  urn a pointer to
2d330 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 0a 2a   the allocated.*
2d340 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72  *          memor
2d350 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 33  y..**.** {F16213
2d360 7d 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  } If a memory al
2d370 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
2d380 63 63 75 72 73 20 64 75 72 69 6e 67 0a 2a 2a 20  ccurs during.** 
2d390 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2d3a0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2d3b0 65 78 74 28 43 2c 4e 29 5d 20 74 68 65 6e 20 74  ext(C,N)] then t
2d3c0 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
2d3d0 72 6e 73 20 30 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  rns 0..**.** {F1
2d3e0 36 32 31 35 7d 20 53 65 63 6f 6e 64 20 61 6e 64  6215} Second and
2d3f0 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
2d400 63 61 74 69 6f 6e 73 20 6f 66 0a 2a 2a 20 20 20  cations of.**   
2d410 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2d420 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2d430 74 28 43 2c 4e 29 5d 20 66 6f 72 20 74 68 65 20  t(C,N)] for the 
2d440 73 61 6d 65 20 63 6f 6e 74 65 78 74 20 70 6f 69  same context poi
2d450 6e 74 65 72 20 43 0a 2a 2a 20 20 20 20 20 20 20  nter C.**       
2d460 20 20 20 69 67 6e 6f 72 65 20 74 68 65 20 4e 20     ignore the N 
2d470 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
2d480 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74  turn a pointer t
2d490 6f 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  o the same.**   
2d4a0 20 20 20 20 20 20 20 62 6c 6f 63 6b 20 6f 66 20         block of 
2d4b0 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
2d4c0 62 79 20 74 68 65 20 66 69 72 73 74 20 69 6e 76  by the first inv
2d4d0 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b  ocation..**.** {
2d4e0 46 31 36 32 31 37 7d 20 54 68 65 20 6d 65 6d 6f  F16217} The memo
2d4f0 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ry allocated by 
2d500 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
2d510 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d  te_context(C,N)]
2d520 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
2d530 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
2d540 65 65 64 20 6f 6e 20 74 68 65 20 6e 65 78 74 20  eed on the next 
2d550 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2d560 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 20 20 20  _reset()].**    
2d570 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65        or [sqlite
2d580 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 66 6f  3_finalize()] fo
2d590 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2d5a0 73 74 61 74 65 6d 65 6e 74 5d 20 63 6f 6e 74 61  statement] conta
2d5b0 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  ining.**        
2d5c0 20 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20    the aggregate 
2d5d0 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61  function associa
2d5e0 74 65 64 20 77 69 74 68 20 63 6f 6e 74 65 78 74  ted with context
2d5f0 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c   C..*/.void *sql
2d600 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2d610 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
2d620 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
2d630 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
2d640 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
2d650 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b   For Functions {
2d660 46 31 36 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F16240}.**.** Th
2d670 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
2d680 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
2d690 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2d6a0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
2d6b0 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
2d6c0 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
2d6d0 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
2d6e0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
2d6f0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2d700 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
2d710 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2d720 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2d730 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
2d740 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
2d750 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
2d760 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
2d770 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a  function. {END}.
2d780 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2d790 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
2d7a0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2d7b0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
2d7c0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
2d7d0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2d7e0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2d7f0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2d800 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 34 33 7d  :.**.** {F16243}
2d810 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 73   The [sqlite3_us
2d820 65 72 5f 64 61 74 61 28 43 29 5d 20 69 6e 74 65  er_data(C)] inte
2d830 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2d840 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20  copy of the.**  
2d850 20 20 20 20 20 20 20 20 50 20 70 6f 69 6e 74 65          P pointe
2d860 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  r from the [sqli
2d870 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2d880 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  ion(D,X,N,E,P,F,
2d890 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,L)].**        
2d8a0 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72    or [sqlite3_cr
2d8b0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2d8c0 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
2d8d0 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20  ] call that.**  
2d8e0 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
2d8f0 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ed the SQL funct
2d900 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77  ion associated w
2d910 69 74 68 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  ith .**         
2d920 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
2d930 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  t] C..*/.void *s
2d940 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
2d950 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2d960 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2d970 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
2d980 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e  nnection For Fun
2d990 63 74 69 6f 6e 73 20 7b 46 31 36 32 35 30 7d 0a  ctions {F16250}.
2d9a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2d9b0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
2d9c0 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  dle() interface 
2d9d0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2d9e0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
2d9f0 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
2da00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
2da10 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
2da20 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
2da30 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2da40 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
2da50 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2da60 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
2da70 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
2da80 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
2da90 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
2daa0 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
2dab0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  tion..**.** INVA
2dac0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
2dad0 31 36 32 35 33 7d 20 54 68 65 20 5b 73 71 6c 69  16253} The [sqli
2dae0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
2daf0 61 6e 64 6c 65 28 43 29 5d 20 69 6e 74 65 72 66  andle(C)] interf
2db00 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
2db10 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  py of the.**    
2db20 20 20 20 20 20 20 44 20 70 6f 69 6e 74 65 72 20        D pointer 
2db30 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
2db40 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2db50 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  n(D,X,N,E,P,F,S,
2db60 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  L)].**          
2db70 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  or [sqlite3_crea
2db80 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c  te_function16(D,
2db90 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20  X,N,E,P,F,S,L)] 
2dba0 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20  call that.**    
2dbb0 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64        registered
2dbc0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2dbd0 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  n associated wit
2dbe0 68 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  h .**          [
2dbf0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
2dc00 20 43 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a   C..*/.sqlite3 *
2dc10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
2dc20 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
2dc30 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
2dc40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
2dc50 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79  nction Auxiliary
2dc60 20 44 61 74 61 20 7b 46 31 36 32 37 30 7d 0a 2a   Data {F16270}.*
2dc70 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
2dc80 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  ng two functions
2dc90 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
2dca0 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
2dcb0 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
2dcc0 69 61 74 65 20 6d 65 74 61 2d 64 61 74 61 20 77  iate meta-data w
2dcd0 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
2dce0 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
2dcf0 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
2dd00 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
2dd10 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
2dd20 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
2dd30 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
2dd40 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
2dd50 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
2dd60 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
2dd70 6f 63 69 61 74 65 64 20 6d 65 74 61 2d 64 61 74  ociated meta-dat
2dd80 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
2dd90 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20  ed. This may.** 
2dda0 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61  be used, for exa
2ddb0 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72  mple, to add a r
2ddc0 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
2ddd0 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61  n matching scala
2dde0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  r.** function. T
2ddf0 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
2de00 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
2de10 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73  ar expression is
2de20 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
2de30 74 61 2d 64 61 74 61 20 61 73 73 6f 63 69 61 74  ta-data associat
2de40 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20  ed with the SQL 
2de50 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
2de60 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
2de70 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72  ession.** patter
2de80 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  n.  The compiled
2de90 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
2dea0 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65  ion can be reuse
2deb0 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  d on multiple.**
2dec0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
2ded0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2dee0 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72  n so that the or
2def0 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73  iginal pattern s
2df00 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tring.** does no
2df10 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63  t need to be rec
2df20 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20  ompiled on each 
2df30 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  invocation..**.*
2df40 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
2df50 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
2df60 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2df70 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
2df80 65 74 61 2d 64 61 74 61 0a 2a 2a 20 61 73 73 6f  eta-data.** asso
2df90 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71  ciated by the sq
2dfa0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2dfb0 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  a() function wit
2dfc0 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  h the Nth argume
2dfd0 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74  nt.** value to t
2dfe0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2dff0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
2e000 0a 2a 2a 20 49 66 20 6e 6f 20 6d 65 74 61 2d 64  .** If no meta-d
2e010 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65  ata has been eve
2e020 72 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74  r been set for t
2e030 68 65 20 4e 74 68 0a 2a 2a 20 61 72 67 75 6d 65  he Nth.** argume
2e040 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  nt of the functi
2e050 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f  on, or if the co
2e060 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63  rresponding func
2e070 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a  tion parameter.*
2e080 2a 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69  * has changed si
2e090 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74  nce the meta-dat
2e0a0 61 20 77 61 73 20 73 65 74 2c 20 74 68 65 6e 20  a was set, then 
2e0b0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2e0c0 61 74 61 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ata().** returns
2e0d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2e0e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2e0f0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
2e100 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73   interface saves
2e110 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 0a 2a   the meta-data.*
2e120 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
2e130 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
2e140 72 20 61 73 20 74 68 65 20 6d 65 74 61 2d 64 61  r as the meta-da
2e150 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a  ta for the N-th.
2e160 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  ** argument of t
2e170 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2e180 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
2e190 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20    Subsequent.** 
2e1a0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2e1b0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d  _get_auxdata() m
2e1c0 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69 73  ight return this
2e1d0 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61 73   data, if it has
2e1e0 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73  .** not been des
2e1f0 74 72 6f 79 65 64 2e 20 0a 2a 2a 20 49 66 20 69  troyed. .** If i
2e200 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53  t is not NULL, S
2e210 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
2e220 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
2e230 20 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69   .** function gi
2e240 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70  ven by the 4th p
2e250 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2e260 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2e270 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61  ) on.** the meta
2e280 2d 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63  -data when the c
2e290 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e  orresponding fun
2e2a0 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
2e2b0 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68  changes.** or wh
2e2c0 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
2e2d0 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20  ment completes, 
2e2e0 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
2e2f0 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  first..**.** SQL
2e300 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63  ite is free to c
2e310 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74  all the destruct
2e320 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61  or and drop meta
2e330 2d 64 61 74 61 20 6f 6e 0a 2a 2a 20 61 6e 79 20  -data on.** any 
2e340 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79  parameter of any
2e350 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79   function at any
2e360 20 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79   time.  The only
2e370 20 67 75 61 72 61 6e 74 65 65 0a 2a 2a 20 69 73   guarantee.** is
2e380 20 74 68 61 74 20 74 68 65 20 64 65 73 74 72 75   that the destru
2e390 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c  ctor will be cal
2e3a0 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d  led before the m
2e3b0 65 74 61 64 61 74 61 20 69 73 0a 2a 2a 20 64 72  etadata is.** dr
2e3c0 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  opped..**.** In 
2e3d0 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 2d 64  practice, meta-d
2e3e0 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
2e3f0 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
2e400 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65  n calls for.** e
2e410 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20  xpressions that 
2e420 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20  are constant at 
2e430 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68  compile time. Th
2e440 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65  is includes lite
2e450 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e  ral.** values an
2e460 64 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e  d SQL variables.
2e470 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2e480 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
2e490 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
2e4a0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
2e4b0 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  ch.** the SQL fu
2e4c0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
2e4d0 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  g..**.** INVARIA
2e4e0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  NTS:.**.** {F162
2e4f0 37 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  72} The [sqlite3
2e500 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _get_auxdata(C,N
2e510 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
2e520 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  urns a pointer.*
2e530 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 6d 65  *          to me
2e540 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
2e550 64 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 70  d with the Nth p
2e560 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
2e570 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  SQL function.** 
2e580 20 20 20 20 20 20 20 20 20 77 68 6f 73 65 20 63           whose c
2e590 6f 6e 74 65 78 74 20 69 73 20 43 2c 20 6f 72 20  ontext is C, or 
2e5a0 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73  NULL if there is
2e5b0 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73   no metadata ass
2e5c0 6f 63 69 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  ociated.**      
2e5d0 20 20 20 20 77 69 74 68 20 74 68 61 74 20 70 61      with that pa
2e5e0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
2e5f0 46 31 36 32 37 34 7d 20 54 68 65 20 5b 73 71 6c  F16274} The [sql
2e600 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2e610 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 72  (C,N,P,D)] inter
2e620 66 61 63 65 20 61 73 73 69 67 6e 73 20 61 20 6d  face assigns a m
2e630 65 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20  etadata.**      
2e640 20 20 20 20 70 6f 69 6e 74 65 72 20 50 20 74 6f      pointer P to
2e650 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74   the Nth paramet
2e660 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  er of the SQL fu
2e670 6e 63 74 69 6f 6e 20 77 69 74 68 20 63 6f 6e 74  nction with cont
2e680 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ext.**          
2e690 43 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 36  C..**.** {F16276
2e6a0 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  } SQLite will in
2e6b0 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
2e6c0 74 6f 72 20 44 20 77 69 74 68 20 61 20 73 69 6e  tor D with a sin
2e6d0 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  gle argument.** 
2e6e0 20 20 20 20 20 20 20 20 20 77 68 69 63 68 20 69           which i
2e6f0 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 70  s the metadata p
2e700 6f 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69  ointer P followi
2e710 6e 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  ng a call to.** 
2e720 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2e730 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
2e740 4e 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53 51 4c  N,P,D)] when SQL
2e750 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f  ite ceases to ho
2e760 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ld.**          t
2e770 68 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a 2a 0a  he metadata..**.
2e780 2a 2a 20 7b 46 31 36 32 37 37 7d 20 53 51 4c 69  ** {F16277} SQLi
2e790 74 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c  te ceases to hol
2e7a0 64 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 61  d metadata for a
2e7b0 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70  n SQL function p
2e7c0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20  arameter.**     
2e7d0 20 20 20 20 20 77 68 65 6e 20 74 68 65 20 76 61       when the va
2e7e0 6c 75 65 20 6f 66 20 74 68 61 74 20 70 61 72 61  lue of that para
2e7f0 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2e 0a 2a  meter changes..*
2e800 2a 0a 2a 2a 20 7b 46 31 36 32 37 38 7d 20 57 68  *.** {F16278} Wh
2e810 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  en [sqlite3_set_
2e820 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29  auxdata(C,N,P,D)
2e830 5d 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68  ] is invoked, th
2e840 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
2e850 20 20 20 20 20 20 20 20 20 69 73 20 63 61 6c 6c           is call
2e860 65 64 20 66 6f 72 20 61 6e 79 20 70 72 69 6f 72  ed for any prior
2e870 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
2e880 61 74 65 64 20 77 69 74 68 20 74 68 65 20 73 61  ated with the sa
2e890 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20  me function.**  
2e8a0 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20          context 
2e8b0 43 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20  C and parameter 
2e8c0 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 39  N..**.** {F16279
2e8d0 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 61  } SQLite will ca
2e8e0 6c 6c 20 64 65 73 74 72 75 63 74 6f 72 73 20 66  ll destructors f
2e8f0 6f 72 20 61 6e 79 20 6d 65 74 61 64 61 74 61 20  or any metadata 
2e900 69 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a  it is holding.**
2e910 20 20 20 20 20 20 20 20 20 20 69 6e 20 61 20 70            in a p
2e920 61 72 74 69 63 75 6c 61 72 20 5b 70 72 65 70 61  articular [prepa
2e930 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2e940 20 77 68 65 6e 20 65 69 74 68 65 72 0a 2a 2a 20   when either.** 
2e950 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2e960 33 5f 72 65 73 65 74 28 53 29 5d 20 6f 72 20 5b  3_reset(S)] or [
2e970 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e980 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a  (S)] is called..
2e990 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
2e9a0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _get_auxdata(sql
2e9b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2e9c0 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt N);.void sqli
2e9d0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2e9e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2e9f0 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20  , int N, void*, 
2ea00 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29  void (*)(void*))
2ea10 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
2ea20 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65  EF: Constants De
2ea30 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44  fining Special D
2ea40 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69  estructor Behavi
2ea50 6f 72 20 7b 46 31 30 32 38 30 7d 0a 2a 2a 0a 2a  or {F10280}.**.*
2ea60 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
2ea70 69 61 6c 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ial value for th
2ea80 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61  e destructor tha
2ea90 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61  t is passed in a
2eaa0 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61  s the.** final a
2eab0 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69  rgument to routi
2eac0 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
2ead0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d  3_result_blob()]
2eae0 2e 20 20 49 66 20 74 68 65 20 64 65 73 74 72 75  .  If the destru
2eaf0 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
2eb00 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
2eb10 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
2eb20 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
2eb30 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
2eb40 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
2eb50 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
2eb60 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
2eb70 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54  be destroyed.  T
2eb80 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  he .** SQLITE_TR
2eb90 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
2eba0 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
2ebb0 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
2ebc0 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
2ebd0 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
2ebe0 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
2ebf0 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
2ec00 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
2ec10 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
2ec20 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
2ec30 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
2ec40 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
2ec50 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
2ec60 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
2ec70 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
2ec80 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b  ilers.  See tick
2ec90 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70  et #2191..*/.typ
2eca0 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
2ecb0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
2ecc0 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
2ecd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
2ece0 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
2ecf0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
2ed00 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
2ed10 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
2ed20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
2ed30 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
2ed40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2ed50 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
2ed60 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
2ed70 74 69 6f 6e 20 7b 46 31 36 34 30 30 7d 0a 2a 2a  tion {F16400}.**
2ed80 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2ed90 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74  es are used by t
2eda0 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e  he xFunc or xFin
2edb0 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  al callbacks tha
2edc0 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53  t.** implement S
2edd0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
2ede0 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65   aggregates.  Se
2edf0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  e.** [sqlite3_cr
2ee00 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2ee10 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
2ee20 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2ee30 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69  )].** for additi
2ee40 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2ee50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  ..**.** These fu
2ee60 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72  nctions work ver
2ee70 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20  y much like the 
2ee80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2ee90 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
2eea0 5f 62 69 6e 64 5f 2a 5d 20 66 61 6d 69 6c 79 20  _bind_*] family 
2eeb0 6f 66 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  of functions use
2eec0 64 0a 2a 2a 20 74 6f 20 62 69 6e 64 20 76 61 6c  d.** to bind val
2eed0 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
2eee0 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
2eef0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
2ef00 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 0a 2a  * Refer to the.*
2ef10 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2ef20 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
2ef30 69 6e 64 5f 2a 20 64 6f 63 75 6d 65 6e 74 61 74  ind_* documentat
2ef40 69 6f 6e 5d 20 66 6f 72 0a 2a 2a 20 61 64 64 69  ion] for.** addi
2ef50 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
2ef60 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  on..**.** The sq
2ef70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2ef80 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  b() interface se
2ef90 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
2efa0 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
2efb0 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
2efc0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
2efd0 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65  BLOB whose conte
2efe0 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a  nt is pointed.**
2eff0 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e   to by the secon
2f000 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
2f010 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73  which is N bytes
2f020 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73   long where N is
2f030 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   the.** third pa
2f040 72 61 6d 65 74 65 72 2e 20 0a 2a 2a 20 54 68 65  rameter. .** The
2f050 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f060 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72  zeroblob() inter
2f070 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65  faces set the re
2f080 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
2f090 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2f0a0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2f0b0 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e  e a BLOB contain
2f0c0 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20  ing all zero.** 
2f0d0 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65  bytes and N byte
2f0e0 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65  s in size, where
2f0f0 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20   N is the value 
2f100 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  of the 2nd param
2f110 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eter..**.** The 
2f120 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
2f130 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  ouble() interfac
2f140 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
2f150 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
2f160 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
2f170 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2f180 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
2f190 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
2f1a0 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61  .** by its 2nd a
2f1b0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
2f1c0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2f1d0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
2f1e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2f1f0 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
2f200 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
2f210 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
2f220 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
2f230 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a  an exception..**
2f240 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
2f250 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
2f260 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64  to by the.** 2nd
2f270 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
2f280 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2f290 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  or() or sqlite3_
2f2a0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
2f2b0 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20  .** as the text 
2f2c0 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  of an error mess
2f2d0 61 67 65 2e 20 20 53 51 4c 69 74 65 20 69 6e 74  age.  SQLite int
2f2e0 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f  erprets the erro
2f2f0 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72  r.** message str
2f300 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
2f310 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
2f320 61 73 20 55 54 46 38 2e 20 53 51 4c 69 74 65 0a  as UTF8. SQLite.
2f330 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  ** interprets th
2f340 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
2f350 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2f360 6f 72 31 36 28 29 20 61 73 20 55 54 46 31 36 20  or16() as UTF16 
2f370 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74  in native.** byt
2f380 65 20 6f 72 64 65 72 2e 20 20 49 66 20 74 68 65  e order.  If the
2f390 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2f3a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
2f3b0 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
2f3c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f3d0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67  error16() is neg
2f3e0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
2f3f0 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65  e takes as the e
2f400 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
2f410 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f  all text up thro
2f420 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
2f430 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
2f440 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61   If the third pa
2f450 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2f460 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2f470 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
2f480 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
2f490 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
2f4a0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
2f4b0 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20  es that many.** 
2f4c0 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
2f4d0 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20  cters) from the 
2f4e0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  2nd parameter as
2f4f0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
2f500 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ge..** The sqlit
2f510 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2f520 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
2f530 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
2f540 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20  * routines make 
2f550 61 20 63 6f 70 79 20 70 72 69 76 61 74 65 20 63  a copy private c
2f560 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72  opy of the error
2f570 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65   message text be
2f580 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74  fore.** they ret
2f590 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  urn.  Hence, the
2f5a0 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
2f5b0 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65  n can deallocate
2f5c0 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68   or.** modify th
2f5d0 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65  e text after the
2f5e0 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74  y return without
2f5f0 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 71   harm..** The sq
2f600 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2f610 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69  or_code() functi
2f620 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65  on changes the e
2f630 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74  rror code.** ret
2f640 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20  urned by SQLite 
2f650 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61  as a result of a
2f660 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e  n error in a fun
2f670 63 74 69 6f 6e 2e 20 20 42 79 20 64 65 66 61 75  ction.  By defau
2f680 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  lt,.** the error
2f690 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f   code is SQLITE_
2f6a0 45 52 52 4f 52 2e 20 20 41 20 73 75 62 73 65 71  ERROR.  A subseq
2f6b0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
2f6c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2f6d0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
2f6e0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2f6f0 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72  () resets the er
2f700 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49  ror code to SQLI
2f710 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20  TE_ERROR..**.** 
2f720 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2f730 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65  lt_toobig() inte
2f740 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
2f750 69 74 65 0a 2a 2a 20 74 6f 20 74 68 72 6f 77 20  ite.** to throw 
2f760 61 6e 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74  an error indicat
2f770 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e  ing that a strin
2f780 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 20  g or BLOB is to 
2f790 6c 6f 6e 67 0a 2a 2a 20 74 6f 20 72 65 70 72 65  long.** to repre
2f7a0 73 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74  sent.  The sqlit
2f7b0 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28  e3_result_nomem(
2f7c0 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 63  ) interface.** c
2f7d0 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
2f7e0 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69  throw an excepti
2f7f0 6f 6e 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  on indicating th
2f800 61 74 20 74 68 65 20 61 0a 2a 2a 20 6d 65 6d 6f  at the a.** memo
2f810 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
2f820 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  iled..**.** The 
2f830 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
2f840 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
2f850 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
2f860 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
2f870 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2f880 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2f890 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
2f8a0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
2f8b0 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
2f8c0 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
2f8d0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2f8e0 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
2f8f0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
2f900 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
2f910 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2f920 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2f930 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
2f940 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
2f950 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
2f960 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
2f970 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
2f980 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2f990 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
2f9a0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
2f9b0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
2f9c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2f9d0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2f9e0 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
2f9f0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
2fa00 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c  sult_text(), sql
2fa10 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2fa20 31 36 28 29 2c 20 0a 2a 2a 20 73 71 6c 69 74 65  16(), .** sqlite
2fa30 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
2fa40 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
2fa50 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
2fa60 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
2fa70 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
2fa80 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
2fa90 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2faa0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
2fab0 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
2fac0 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
2fad0 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
2fae0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
2faf0 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
2fb00 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
2fb10 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
2fb20 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
2fb30 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65  ively..** SQLite
2fb40 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20   takes the text 
2fb50 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20  result from the 
2fb60 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d  application from
2fb70 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61  .** the 2nd para
2fb80 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c  meter of the sql
2fb90 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2fba0 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  * interfaces..**
2fbb0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
2fbc0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
2fbd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2fbe0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
2fbf0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2fc00 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72  n SQLite takes r
2fc10 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20  esult text from 
2fc20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2fc30 72 20 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68  r .** through th
2fc40 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
2fc50 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68  racter..** If th
2fc60 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
2fc70 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
2fc80 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2fc90 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e  rfaces.** is non
2fca0 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
2fcb0 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e  as many bytes (n
2fcc0 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f  ot characters) o
2fcd0 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f  f the text.** po
2fce0 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
2fcf0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72  2nd parameter ar
2fd00 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61  e taken as the a
2fd10 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2fd20 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  ed.** function r
2fd30 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65  esult..** If the
2fd40 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
2fd50 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
2fd60 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
2fd70 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
2fd80 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
2fd90 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  is a non-NULL po
2fda0 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
2fdb0 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a  te calls that.**
2fdc0 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65   function as the
2fdd0 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
2fde0 68 65 20 74 65 78 74 20 6f 72 20 62 6c 6f 62 20  he text or blob 
2fdf0 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68  result when it h
2fe00 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75  as.** finished u
2fe10 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
2fe20 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20  ..** If the 4th 
2fe30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2fe40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2fe50 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
2fe60 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
2fe70 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
2fe80 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
2fe90 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  nt SQLITE_STATIC
2fea0 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
2feb0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
2fec0 65 20 74 65 78 74 20 6f 72 20 62 6c 6f 62 20 72  e text or blob r
2fed0 65 73 75 6c 74 20 69 73 20 63 6f 6e 73 74 61 6e  esult is constan
2fee0 74 20 73 70 61 63 65 20 61 6e 64 0a 2a 2a 20 64  t space and.** d
2fef0 6f 65 73 20 6e 6f 74 20 63 6f 70 79 20 74 68 65  oes not copy the
2ff00 20 73 70 61 63 65 20 6f 72 20 63 61 6c 6c 20 61   space or call a
2ff10 20 64 65 73 74 72 75 63 74 6f 72 20 77 68 65 6e   destructor when
2ff20 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73   it has.** finis
2ff30 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
2ff40 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65  esult..** If the
2ff50 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
2ff60 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
2ff70 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
2ff80 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
2ff90 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
2ffa0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
2ffb0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54  onstant SQLITE_T
2ffc0 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e  RANSIENT.** then
2ffd0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20   SQLite makes a 
2ffe0 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75  copy of the resu
2fff0 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62  lt into space ob
30000 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66  tained from.** f
30010 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
30020 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74  loc()] before it
30030 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
30040 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
30050 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
30060 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
30070 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
30080 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
30090 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
300a0 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20  e a copy the.** 
300b0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
300c0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
300d0 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ct specified by 
300e0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
300f0 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  r.  The.** sqlit
30100 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
30110 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
30120 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
30130 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
30140 2a 2a 20 73 6f 20 74 68 61 74 20 5b 73 71 6c 69  ** so that [sqli
30150 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69  te3_value] speci
30160 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61  fied in the para
30170 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65  meter may change
30180 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f   or.** be deallo
30190 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  cated after sqli
301a0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
301b0 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f  () returns witho
301c0 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70  ut harm..** A [p
301d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
301e0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d  _value] object m
301f0 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65  ay always be use
30200 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75  d where an.** [u
30210 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
30220 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
30230 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f   is required, so
30240 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20   either.** kind 
30250 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  of [sqlite3_valu
30260 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65  e] object can be
30270 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20   used with this 
30280 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
30290 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   If these routin
302a0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  es are called fr
302b0 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69  om within the di
302c0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 0a  fferent thread .
302d0 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
302e0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
302f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
30300 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
30310 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65   received.** the
30320 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
30330 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
30340 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
30350 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  fined..**.** INV
30360 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
30370 46 31 36 34 30 33 7d 20 54 68 65 20 64 65 66 61  F16403} The defa
30380 75 6c 74 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ult return value
30390 20 66 72 6f 6d 20 61 6e 79 20 53 51 4c 20 66 75   from any SQL fu
303a0 6e 63 74 69 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a  nction is NULL..
303b0 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 36 7d 20 54  **.** {F16406} T
303c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
303d0 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29  lt_blob(C,V,N,D)
303e0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
303f0 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
30400 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
30410 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
30420 6f 20 62 65 20 61 20 62 6c 6f 62 20 74 68 61 74  o be a blob that
30430 20 69 73 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20   is N bytes.**  
30440 20 20 20 20 20 20 20 20 69 6e 20 6c 65 6e 67 74          in lengt
30450 68 20 61 6e 64 20 77 69 74 68 20 63 6f 6e 74 65  h and with conte
30460 6e 74 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  nt pointed to by
30470 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30   V..**.** {F1640
30480 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
30490 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 43 2c  result_double(C,
304a0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  V)] interface ch
304b0 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
304c0 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
304d0 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
304e0 20 74 6f 20 62 65 20 74 68 65 20 66 6c 6f 61 74   to be the float
304f0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
30500 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31 32  V..**.** {F16412
30510 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
30520 65 73 75 6c 74 5f 65 72 72 6f 72 28 43 2c 56 2c  esult_error(C,V,
30530 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  N)] interface ch
30540 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
30550 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
30560 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
30570 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74   to be an except
30580 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63  ion with error c
30590 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ode.**          
305a0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61  [SQLITE_ERROR] a
305b0 6e 64 20 61 20 55 54 46 38 20 65 72 72 6f 72 20  nd a UTF8 error 
305c0 6d 65 73 73 61 67 65 20 63 6f 70 69 65 64 20 66  message copied f
305d0 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65 0a  rom V up to the.
305e0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 72 73  **          firs
305f0 74 20 7a 65 72 6f 20 62 79 74 65 20 6f 72 20 75  t zero byte or u
30600 6e 74 69 6c 20 4e 20 62 79 74 65 73 20 61 72 65  ntil N bytes are
30610 20 72 65 61 64 20 69 66 20 4e 20 69 73 20 70 6f   read if N is po
30620 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  sitive..**.** {F
30630 31 36 34 31 35 7d 20 54 68 65 20 5b 73 71 6c 69  16415} The [sqli
30640 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
30650 31 36 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72  16(C,V,N)] inter
30660 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
30670 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20   return.**      
30680 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e      value of fun
30690 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
306a0 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
306b0 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20  error code.**   
306c0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45         [SQLITE_E
306d0 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 31  RROR] and a UTF1
306e0 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
306f0 64 65 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67  der error messag
30700 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
30710 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74  pied from V up t
30720 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
30730 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 72 20 75   terminator or u
30740 6e 74 69 6c 20 4e 20 62 79 74 65 73 0a 2a 2a 20  ntil N bytes.** 
30750 20 20 20 20 20 20 20 20 20 61 72 65 20 72 65 61           are rea
30760 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69  d if N is positi
30770 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31  ve..**.** {F1641
30780 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  8} The [sqlite3_
30790 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
307a0 62 69 67 28 43 29 5d 20 69 6e 74 65 72 66 61 63  big(C)] interfac
307b0 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65  e changes the re
307c0 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
307d0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75   value of the fu
307e0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
307f0 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68  n exception with
30800 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20   error code.**  
30810 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
30820 54 4f 4f 42 49 47 5d 20 61 6e 64 20 61 6e 20 61  TOOBIG] and an a
30830 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
30840 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
30850 7b 46 31 36 34 32 31 7d 20 54 68 65 20 5b 73 71  {F16421} The [sq
30860 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30870 6f 72 5f 6e 6f 6d 65 6d 28 43 29 5d 20 69 6e 74  or_nomem(C)] int
30880 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
30890 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20  he return.**    
308a0 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74        value of t
308b0 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  he function C to
308c0 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e   be an exception
308d0 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65   with error code
308e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
308f0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20  LITE_NOMEM] and 
30900 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65  an appropriate e
30910 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
30920 0a 2a 2a 20 7b 46 31 36 34 32 34 7d 20 54 68 65  .** {F16424} The
30930 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
30940 5f 65 72 72 6f 72 5f 63 6f 64 65 28 43 2c 45 29  _error_code(C,E)
30950 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
30960 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
30970 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
30980 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
30990 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65   C to be an exce
309a0 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72  ption with error
309b0 20 63 6f 64 65 20 45 2e 0a 2a 2a 20 20 20 20 20   code E..**     
309c0 20 20 20 20 20 54 68 65 20 65 72 72 6f 72 20 6d       The error m
309d0 65 73 73 61 67 65 20 74 65 78 74 20 69 73 20 75  essage text is u
309e0 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20  nchanged..**.** 
309f0 7b 46 31 36 34 32 37 7d 20 54 68 65 20 5b 73 71  {F16427} The [sq
30a00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
30a10 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,V)] interface
30a20 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
30a30 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
30a40 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
30a50 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 33 32  n C to be the 32
30a60 2d 62 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c  -bit integer val
30a70 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ue V..**.** {F16
30a80 34 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  430} The [sqlite
30a90 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 43  3_result_int64(C
30aa0 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,V)] interface c
30ab0 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
30ac0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
30ad0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
30ae0 43 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62  C to be the 64-b
30af0 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  it integer value
30b00 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33   V..**.** {F1643
30b10 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
30b20 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20  result_null(C)] 
30b30 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
30b40 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
30b50 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
30b60 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
30b70 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b  be NULL..**.** {
30b80 46 31 36 34 33 36 7d 20 54 68 65 20 5b 73 71 6c  F16436} The [sql
30b90 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
30ba0 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72  (C,V,N,D)] inter
30bb0 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
30bc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
30bd0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
30be0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
30bf0 65 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a  e UTF8 string.**
30c00 20 20 20 20 20 20 20 20 20 20 56 20 75 70 20 74            V up t
30c10 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
30c20 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76   if N is negativ
30c30 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  e.**          or
30c40 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74   the first N byt
30c50 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20  es of V if N is 
30c60 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a  non-negative..**
30c70 0a 2a 2a 20 7b 46 31 36 34 33 39 7d 20 54 68 65  .** {F16439} The
30c80 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
30c90 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29  _text16(C,V,N,D)
30ca0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
30cb0 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
30cc0 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
30cd0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
30ce0 6f 20 62 65 20 74 68 65 20 55 54 46 31 36 20 6e  o be the UTF16 n
30cf0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
30d00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
30d10 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65 20  ing V up to the 
30d20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20  first zero if N 
30d30 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  is.**          n
30d40 65 67 61 74 69 76 65 20 6f 72 20 74 68 65 20 66  egative or the f
30d50 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20  irst N bytes of 
30d60 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65  V if N is non-ne
30d70 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  gative..**.** {F
30d80 31 36 34 34 32 7d 20 54 68 65 20 5b 73 71 6c 69  16442} The [sqli
30d90 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
30da0 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e  6be(C,V,N,D)] in
30db0 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
30dc0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
30dd0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
30de0 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
30df0 20 74 68 65 20 55 54 46 31 36 20 62 69 67 2d 65   the UTF16 big-e
30e00 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ndian.**        
30e10 20 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f    string V up to
30e20 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
30e30 69 66 20 4e 20 69 73 0a 2a 2a 20 20 20 20 20 20  if N is.**      
30e40 20 20 20 20 69 73 20 6e 65 67 61 74 69 76 65 20      is negative 
30e50 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62  or the first N b
30e60 79 74 65 73 20 6f 72 20 56 20 69 66 20 4e 20 69  ytes or V if N i
30e70 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a  s non-negative..
30e80 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34 35 7d 20 54  **.** {F16445} T
30e90 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
30ea0 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c  lt_text16le(C,V,
30eb0 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  N,D)] interface 
30ec0 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
30ed0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
30ee0 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
30ef0 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46   C to be the UTF
30f00 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  16 little-endian
30f10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
30f20 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65 20  ing V up to the 
30f30 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20  first zero if N 
30f40 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  is.**          n
30f50 65 67 61 74 69 76 65 20 6f 72 20 74 68 65 20 66  egative or the f
30f60 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20  irst N bytes of 
30f70 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65  V if N is non-ne
30f80 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  gative..**.** {F
30f90 31 36 34 34 38 7d 20 54 68 65 20 5b 73 71 6c 69  16448} The [sqli
30fa0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
30fb0 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,V)] interface
30fc0 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
30fd0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
30fe0 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
30ff0 6e 20 43 20 74 6f 20 62 65 20 5b 75 6e 70 72 6f  n C to be [unpro
31000 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
31010 61 6c 75 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20  alue].**        
31020 20 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a    object V..**.*
31030 2a 20 7b 46 31 36 34 35 31 7d 20 54 68 65 20 5b  * {F16451} The [
31040 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
31050 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e  eroblob(C,N)] in
31060 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
31070 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
31080 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
31090 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
310a0 20 61 6e 20 4e 2d 62 79 74 65 20 62 6c 6f 62 20   an N-byte blob 
310b0 6f 66 20 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a  of all zeros..**
310c0 0a 2a 2a 20 7b 46 31 36 34 35 34 7d 20 54 68 65  .** {F16454} The
310d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
310e0 5f 65 72 72 6f 72 28 29 5d 20 61 6e 64 20 5b 73  _error()] and [s
310f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31100 72 6f 72 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20  ror16()].**     
31110 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20       interfaces 
31120 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74  make a copy of t
31130 68 65 69 72 20 65 72 72 6f 72 20 6d 65 73 73 61  heir error messa
31140 67 65 20 73 74 72 69 6e 67 73 20 62 65 66 6f 72  ge strings befor
31150 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
31160 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b  turning..**.** {
31170 46 31 36 34 35 37 7d 20 49 66 20 74 68 65 20 44  F16457} If the D
31180 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61   destructor para
31190 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
311a0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c  3_result_blob(C,
311b0 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,N,D)],.**     
311c0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
311d0 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c  sult_text(C,V,N,
311e0 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  D)], [sqlite3_re
311f0 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c  sult_text16(C,V,
31200 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  N,D)],.**       
31210 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
31220 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c  lt_text16be(C,V,
31230 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  N,D)], or.**    
31240 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
31250 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43  esult_text16le(C
31260 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20  ,V,N,D)] is the 
31270 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45  constant [SQLITE
31280 5f 53 54 41 54 49 43 5d 0a 2a 2a 20 20 20 20 20  _STATIC].**     
31290 20 20 20 20 20 74 68 65 6e 20 6e 6f 20 64 65 73       then no des
312a0 74 72 75 63 74 6f 72 20 69 73 20 65 76 65 72 20  tructor is ever 
312b0 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 70 6f  called on the po
312c0 69 6e 74 65 72 20 56 20 61 6e 64 20 53 51 4c 69  inter V and SQLi
312d0 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  te.**          a
312e0 73 73 75 6d 65 73 20 74 68 61 74 20 56 20 69 73  ssumes that V is
312f0 20 69 6d 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a   immutable..**.*
31300 2a 20 7b 46 31 36 34 36 30 7d 20 49 66 20 74 68  * {F16460} If th
31310 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70  e D destructor p
31320 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
31330 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
31340 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20  (C,V,N,D)],.**  
31350 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
31360 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56  _result_text(C,V
31370 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ,N,D)], [sqlite3
31380 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43  _result_text16(C
31390 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,N,D)],.**    
313a0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
313b0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43  esult_text16be(C
313c0 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,N,D)], or.** 
313d0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
313e0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
313f0 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74  e(C,V,N,D)] is t
31400 68 65 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20  he constant.**  
31410 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
31420 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20  TRANSIENT] then 
31430 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  the interfaces m
31440 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
31450 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  he.**          c
31460 6f 6e 74 65 6e 74 20 6f 66 20 56 20 61 6e 64 20  ontent of V and 
31470 72 65 74 61 69 6e 73 20 74 68 65 20 63 6f 70 79  retains the copy
31480 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 36 33 7d  ..**.** {F16463}
31490 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72 75   If the D destru
314a0 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74  ctor parameter t
314b0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
314c0 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d  t_blob(C,V,N,D)]
314d0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
314e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
314f0 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73  xt(C,V,N,D)], [s
31500 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31510 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a  xt16(C,V,N,D)],.
31520 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
31530 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
31540 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20  16be(C,V,N,D)], 
31550 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
31560 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31570 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29  ext16le(C,V,N,D)
31580 5d 20 69 73 20 73 6f 6d 65 20 76 61 6c 75 65 20  ] is some value 
31590 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20  other than.**   
315a0 20 20 20 20 20 20 20 74 68 65 20 63 6f 6e 73 74         the const
315b0 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 53 54 41  ants [SQLITE_STA
315c0 54 49 43 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  TIC] and [SQLITE
315d0 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e  _TRANSIENT] then
315e0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51   .**          SQ
315f0 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
31600 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
31610 44 20 77 69 74 68 20 56 20 61 73 20 69 74 73 20  D with V as its 
31620 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  only argument.**
31630 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 20 69            when i
31640 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
31650 69 74 68 20 74 68 65 20 56 20 76 61 6c 75 65 2e  ith the V value.
31660 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
31670 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c  _result_blob(sql
31680 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
31690 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
316a0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
316b0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
316c0 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c  esult_double(sql
316d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64  ite3_context*, d
316e0 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c  ouble);.void sql
316f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31700 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  r(sqlite3_contex
31710 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
31720 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
31730 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31740 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
31750 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
31760 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
31770 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31780 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33  r_toobig(sqlite3
31790 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
317a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
317b0 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69  error_nomem(sqli
317c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
317d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
317e0 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71  lt_error_code(sq
317f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
31800 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
31810 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71  e3_result_int(sq
31820 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
31830 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
31840 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
31850 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31860 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
31870 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
31880 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
31890 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
318a0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
318b0 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  t_text(sqlite3_c
318c0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
318d0 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  har*, int, void(
318e0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
318f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31900 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63  text16(sqlite3_c
31910 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
31920 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
31930 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
31940 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31950 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
31960 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
31970 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
31980 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
31990 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
319a0 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
319b0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
319c0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
319d0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
319e0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
319f0 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  t_value(sqlite3_
31a00 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
31a10 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20  3_value*);.void 
31a20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
31a30 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
31a40 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29  context*, int n)
31a50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31a60 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f  F: Define New Co
31a70 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65  llating Sequence
31a80 73 20 7b 46 31 36 36 30 30 7d 0a 2a 2a 0a 2a 2a  s {F16600}.**.**
31a90 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
31aa0 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
31ab0 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   new collation s
31ac0 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a  equences to the.
31ad0 2a 2a 20 5b 73 71 6c 69 74 65 33 2a 5d 20 68 61  ** [sqlite3*] ha
31ae0 6e 64 6c 65 20 73 70 65 63 69 66 69 65 64 20 61  ndle specified a
31af0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
31b00 6d 65 6e 74 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ment. .**.** The
31b10 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77   name of the new
31b20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
31b30 6e 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64  nce is specified
31b40 20 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   as a UTF-8 stri
31b50 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65  ng.** for sqlite
31b60 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
31b70 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  on() and sqlite3
31b80 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
31b90 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20  n_v2().** and a 
31ba0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f  UTF-16 string fo
31bb0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
31bc0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20  _collation16(). 
31bd0 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20  In all cases.** 
31be0 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73  the name is pass
31bf0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
31c00 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
31c10 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  nt..**.** The th
31c20 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79  ird argument may
31c30 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   be one of the c
31c40 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45  onstants [SQLITE
31c50 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _UTF8],.** [SQLI
31c60 54 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b  TE_UTF16LE] or [
31c70 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
31c80 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
31c90 20 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69   the user-suppli
31ca0 65 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78  ed.** routine ex
31cb0 70 65 63 74 73 20 74 6f 20 62 65 20 70 61 73 73  pects to be pass
31cc0 65 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  ed pointers to s
31cd0 74 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75  trings encoded u
31ce0 73 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55  sing UTF-8,.** U
31cf0 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64  TF-16 little-end
31d00 69 61 6e 20 6f 72 20 55 54 46 2d 31 36 20 62 69  ian or UTF-16 bi
31d10 67 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  g-endian respect
31d20 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68  ively. The.** th
31d30 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67  ird argument mig
31d40 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49  ht also be [SQLI
31d50 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
31d60 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  ] to indicate th
31d70 61 74 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e  at.** the routin
31d80 65 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65  e expects pointe
31d90 72 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72  rs to 16-bit wor
31da0 64 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67  d aligned string
31db0 73 0a 2a 2a 20 6f 66 20 55 54 46 31 36 20 69 6e  s.** of UTF16 in
31dc0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
31dd0 20 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f   order of the ho
31de0 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a  st computer..**.
31df0 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
31e00 74 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65  the user supplie
31e10 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  d routine must b
31e20 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
31e30 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e  fifth.** argumen
31e40 74 2e 20 20 49 66 20 69 74 20 69 73 20 4e 55 4c  t.  If it is NUL
31e50 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 73  L, this is the s
31e60 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20  ame as deleting 
31e70 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
31e80 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68   sequence (so th
31e90 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74  at SQLite cannot
31ea0 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65   call it anymore
31eb0 29 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65 20  )..** Each time 
31ec0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  the application.
31ed0 2a 2a 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63  ** supplied func
31ee0 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c  tion is invoked,
31ef0 20 69 74 20 69 73 20 70 61 73 73 65 64 20 61 20   it is passed a 
31f00 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
31f10 2a 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74  * passed as.** t
31f20 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
31f30 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  nt to sqlite3_cr
31f40 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
31f50 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
31f60 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
31f70 36 28 29 20 61 73 20 69 74 73 20 66 69 72 73 74  6() as its first
31f80 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
31f90 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
31fa0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
31fb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
31fc0 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72  plied routine ar
31fd0 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a  e two strings,.*
31fe0 2a 20 65 61 63 68 20 72 65 70 72 65 73 65 6e 74  * each represent
31ff0 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c  ed by a (length,
32000 20 64 61 74 61 29 20 70 61 69 72 20 61 6e 64 20   data) pair and 
32010 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65  encoded in the e
32020 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20  ncoding.** that 
32030 77 61 73 20 70 61 73 73 65 64 20 61 73 20 74 68  was passed as th
32040 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
32050 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   when the collat
32060 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73  ion sequence was
32070 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20  .** registered. 
32080 7b 45 4e 44 7d 20 54 68 65 20 61 70 70 6c 69 63  {END} The applic
32090 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f  ation defined co
320a0 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20  llation routine 
320b0 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
320c0 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20   negative, zero 
320d0 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 0a 2a  or positive if.*
320e0 2a 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69  * the first stri
320f0 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c  ng is less than,
32100 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72   equal to, or gr
32110 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73  eater than the s
32120 65 63 6f 6e 64 0a 2a 2a 20 73 74 72 69 6e 67 2e  econd.** string.
32130 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d   i.e. (STRING1 -
32140 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a   STRING2)..**.**
32150 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65   The sqlite3_cre
32160 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
32170 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  () works like sq
32180 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
32190 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65  lation().** exce
321a0 70 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 73  pt that it takes
321b0 20 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65   an extra argume
321c0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 64 65  nt which is a de
321d0 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20  structor for.** 
321e0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20  the collation.  
321f0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
32200 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  s called when th
32210 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a  e collation is.*
32220 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20  * destroyed and 
32230 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79  is passed a copy
32240 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
32250 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70  arameter void* p
32260 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65  ointer.** of the
32270 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32280 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a  collation_v2()..
32290 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72  ** Collations ar
322a0 65 20 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e  e destroyed when
322b0 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 6f 76 65  .** they are ove
322c0 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
322d0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f   calls to the co
322e0 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  llation creation
322f0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6f 72   functions.** or
32300 20 77 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   when the [sqlit
32310 65 33 2a 5d 20 64 61 74 61 62 61 73 65 20 68 61  e3*] database ha
32320 6e 64 6c 65 20 69 73 20 63 6c 6f 73 65 64 20 75  ndle is closed u
32330 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c  sing [sqlite3_cl
32340 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  ose()]..**.** IN
32350 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
32360 7b 46 31 36 36 30 33 7d 20 41 20 73 75 63 63 65  {F16603} A succe
32370 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 74 68  ssful call to th
32380 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
32390 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
323a0 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
323b0 2c 50 2c 46 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,P,F,D)] interfa
323c0 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ce.**          r
323d0 65 67 69 73 74 65 72 73 20 66 75 6e 63 74 69 6f  egisters functio
323e0 6e 20 46 20 61 73 20 74 68 65 20 63 6f 6d 70 61  n F as the compa
323f0 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 75  rison function u
32400 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  sed to.**       
32410 20 20 20 69 6d 70 6c 65 6d 65 6e 74 20 63 6f 6c     implement col
32420 6c 61 74 69 6f 6e 20 58 20 6f 6e 20 5b 64 61 74  lation X on [dat
32430 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32440 5d 20 42 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  ] B for.**      
32450 20 20 20 20 64 61 74 61 62 61 73 65 73 20 68 61      databases ha
32460 76 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 45 2e  ving encoding E.
32470 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 34 7d 20  .**.** {F16604} 
32480 53 51 4c 69 74 65 20 75 6e 64 65 72 73 74 61 6e  SQLite understan
32490 64 73 20 74 68 65 20 58 20 70 61 72 61 6d 65 74  ds the X paramet
324a0 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  er to.**        
324b0 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74    [sqlite3_creat
324c0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42  e_collation_v2(B
324d0 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 61 73 20  ,X,E,P,F,D)] as 
324e0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
324f0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54  d.**          UT
32500 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 20 77 68  F-8 string in wh
32510 69 63 68 20 63 61 73 65 20 69 73 20 69 67 6e 6f  ich case is igno
32520 72 65 64 20 66 6f 72 20 41 53 43 49 49 20 63 68  red for ASCII ch
32530 61 72 61 63 74 65 72 73 20 61 6e 64 0a 2a 2a 20  aracters and.** 
32540 20 20 20 20 20 20 20 20 20 69 73 20 73 69 67 6e           is sign
32550 69 66 69 63 61 6e 74 20 66 6f 72 20 6e 6f 6e 2d  ificant for non-
32560 41 53 43 49 49 20 63 68 61 72 61 63 74 65 72 73  ASCII characters
32570 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 36 7d  ..**.** {F16606}
32580 20 53 75 63 63 65 73 73 69 76 65 20 63 61 6c 6c   Successive call
32590 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  s to [sqlite3_cr
325a0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
325b0 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a  2(B,X,E,P,F,D)].
325c0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68  **          with
325d0 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 73   the same values
325e0 20 66 6f 72 20 42 2c 20 58 2c 20 61 6e 64 20 45   for B, X, and E
325f0 2c 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72  , override prior
32600 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20   values.**      
32610 20 20 20 20 6f 66 20 50 2c 20 46 2c 20 61 6e 64      of P, F, and
32620 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30   D..**.** {F1660
32630 39 7d 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  9} The destructo
32640 72 20 44 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  r D in [sqlite3_
32650 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
32660 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
32670 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  ].**          is
32680 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 69   not NULL then i
32690 74 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  t is called with
326a0 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e   argument P when
326b0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
326c0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
326d0 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 62  ion is dropped b
326e0 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  y SQLite..**.** 
326f0 7b 46 31 36 36 31 32 7d 20 41 20 63 6f 6c 6c 61  {F16612} A colla
32700 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
32710 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20 69 74   dropped when it
32720 20 69 73 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a   is overloaded..
32730 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31 35 7d 20 41  **.** {F16615} A
32740 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
32750 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77  ion is dropped w
32760 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
32770 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20   connection.**  
32780 20 20 20 20 20 20 20 20 69 73 20 63 6c 6f 73 65          is close
32790 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
327a0 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
327b0 20 7b 46 31 36 36 31 38 7d 20 54 68 65 20 70 6f   {F16618} The po
327c0 69 6e 74 65 72 20 50 20 69 6e 20 5b 73 71 6c 69  inter P in [sqli
327d0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
327e0 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c  tion_v2(B,X,E,P,
327f0 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  F,D)].**        
32800 20 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f    is passed thro
32810 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
32820 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
32830 65 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20  e comparison.** 
32840 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f           functio
32850 6e 20 46 20 66 6f 72 20 61 6c 6c 20 73 75 62 73  n F for all subs
32860 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
32870 6e 73 20 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b  ns of F..**.** {
32880 46 31 36 36 32 31 7d 20 41 20 63 61 6c 6c 20 74  F16621} A call t
32890 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
328a0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c  e_collation(B,X,
328b0 45 2c 50 2c 46 29 5d 20 69 73 20 65 78 61 63 74  E,P,F)] is exact
328c0 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ly.**          t
328d0 68 65 20 73 61 6d 65 20 61 73 20 61 20 63 61 6c  he same as a cal
328e0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  l to [sqlite3_cr
328f0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
32900 32 28 29 5d 20 77 69 74 68 0a 2a 2a 20 20 20 20  2()] with.**    
32910 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 70        the same p
32920 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 61 20  arameters and a 
32930 4e 55 4c 4c 20 64 65 73 74 72 75 63 74 6f 72 2e  NULL destructor.
32940 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 32 34 7d 20  .**.** {F16624} 
32950 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 5b 73 71 6c  Following a [sql
32960 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
32970 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
32980 2c 46 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,F,D)],.**      
32990 20 20 20 20 53 51 4c 69 74 65 20 75 73 65 73 20      SQLite uses 
329a0 74 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66  the comparison f
329b0 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c  unction F for al
329c0 6c 20 74 65 78 74 20 63 6f 6d 70 61 72 69 73 6f  l text compariso
329d0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 70  n.**          op
329e0 65 72 61 74 69 6f 6e 73 20 6f 6e 20 5b 64 61 74  erations on [dat
329f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32a00 5d 20 42 20 6f 6e 20 74 65 78 74 20 76 61 6c 75  ] B on text valu
32a10 65 73 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20  es that.**      
32a20 20 20 20 20 75 73 65 20 74 68 65 20 63 6f 6c 6c      use the coll
32a30 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20 6e  ating sequence n
32a40 61 6d 65 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ame X..**.** {F1
32a50 36 36 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74  6627} The [sqlit
32a60 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
32a70 69 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 2c 46 29  ion16(B,X,E,P,F)
32a80 5d 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65  ] works the same
32a90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20  .**          as 
32aa0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32ab0 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c  collation(B,X,E,
32ac0 50 2c 46 29 5d 20 65 78 63 65 70 74 20 74 68 61  P,F)] except tha
32ad0 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  t the.**        
32ae0 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65    collation name
32af0 20 58 20 69 73 20 75 6e 64 65 72 73 74 6f 6f 64   X is understood
32b00 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61   as UTF-16 in na
32b10 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a  tive byte order.
32b20 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73 74  **          inst
32b30 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a  ead of UTF-8..**
32b40 0a 2a 2a 20 7b 46 31 36 36 33 30 7d 20 57 68 65  .** {F16630} Whe
32b50 6e 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d 70 61  n multiple compa
32b60 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20  rison functions 
32b70 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 66 6f  are available fo
32b80 72 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  r the same.**   
32b90 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67         collating
32ba0 20 73 65 71 75 65 6e 63 65 2c 20 53 51 4c 69 74   sequence, SQLit
32bb0 65 20 63 68 6f 6f 73 65 73 20 74 68 65 20 6f 6e  e chooses the on
32bc0 65 20 77 68 6f 73 65 20 74 65 78 74 20 65 6e 63  e whose text enc
32bd0 6f 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  oding.**        
32be0 20 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c    requires the l
32bf0 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 63  east amount of c
32c00 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 74  onversion from t
32c10 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20  he default.**   
32c20 20 20 20 20 20 20 20 74 65 78 74 20 65 6e 63 6f         text enco
32c30 64 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61  ding of the data
32c40 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  base..*/.int sql
32c50 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
32c60 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ation(.  sqlite3
32c70 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
32c80 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
32c90 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
32ca0 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
32cb0 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
32cc0 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
32cd0 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69  onst void*).);.i
32ce0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
32cf0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a  e_collation_v2(.
32d00 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
32d10 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
32d20 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
32d30 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
32d40 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
32d50 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
32d60 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
32d70 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  id*),.  void(*xD
32d80 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
32d90 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
32da0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
32db0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
32dc0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
32dd0 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
32de0 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
32df0 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
32e00 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
32e10 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
32e20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
32e30 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61   CAPI3REF: Colla
32e40 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c  tion Needed Call
32e50 62 61 63 6b 73 20 7b 46 31 36 37 30 30 7d 0a 2a  backs {F16700}.*
32e60 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 68 61  *.** To avoid ha
32e70 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72  ving to register
32e80 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   all collation s
32e90 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20  equences before 
32ea0 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61  a database.** ca
32eb0 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e  n be used, a sin
32ec0 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  gle callback fun
32ed0 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
32ee0 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65  istered with the
32ef0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 68 61 6e  .** database han
32f00 64 6c 65 20 74 6f 20 62 65 20 63 61 6c 6c 65 64  dle to be called
32f10 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64   whenever an und
32f20 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
32f30 20 73 65 71 75 65 6e 63 65 20 69 73 0a 2a 2a 20   sequence is.** 
32f40 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
32f50 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
32f60 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73  is registered us
32f70 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
32f80 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
32f90 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20  () API,.** then 
32fa0 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65  it is passed the
32fb0 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69   names of undefi
32fc0 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ned collation se
32fd0 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e  quences as strin
32fe0 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e  gs.** encoded in
32ff0 20 55 54 46 2d 38 2e 20 7b 46 31 36 37 30 33 7d   UTF-8. {F16703}
33000 20 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   If sqlite3_coll
33010 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
33020 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 6e 61   is used, the na
33030 6d 65 73 0a 2a 2a 20 61 72 65 20 70 61 73 73 65  mes.** are passe
33040 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d  d as UTF-16 in m
33050 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79  achine native by
33060 74 65 20 6f 72 64 65 72 2e 20 41 20 63 61 6c 6c  te order. A call
33070 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 66 75   to either.** fu
33080 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20  nction replaces 
33090 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c  any existing cal
330a0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  lback..**.** Whe
330b0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  n the callback i
330c0 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66  s invoked, the f
330d0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61  irst argument pa
330e0 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a  ssed is a copy.*
330f0 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  * of the second 
33100 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
33110 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
33120 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  eded() or.** sql
33130 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
33140 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20  eeded16().  The 
33150 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
33160 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  is the database.
33170 2a 2a 20 68 61 6e 64 6c 65 2e 20 20 54 68 65 20  ** handle.  The 
33180 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
33190 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
331a0 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _UTF8],.** [SQLI
331b0 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20  TE_UTF16BE], or 
331c0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
331d0 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65  , indicating the
331e0 20 6d 6f 73 74 0a 2a 2a 20 64 65 73 69 72 61 62   most.** desirab
331f0 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63  le form of the c
33200 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
33210 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  e function requi
33220 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 75 72  red..** The four
33230 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
33240 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
33250 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c  ** required coll
33260 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a  ation sequence..
33270 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
33280 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  ck function shou
33290 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20  ld register the 
332a0 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  desired collatio
332b0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
332c0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
332d0 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  tion()], [sqlite
332e0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
332f0 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  on16()], or.** [
33300 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
33310 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a  ollation_v2()]..
33320 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
33330 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 37 30 32 7d  :.**.** {F16702}
33340 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
33350 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
33360 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
33370 44 2c 50 2c 46 29 5d 0a 2a 2a 20 20 20 20 20 20  D,P,F)].**      
33380 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
33390 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
333a0 31 36 28 44 2c 50 2c 46 29 5d 20 63 61 75 73 65  16(D,P,F)] cause
333b0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
333c0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
333d0 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20 69 6e 76  ection] D to inv
333e0 6f 6b 65 20 63 61 6c 6c 62 61 63 6b 20 46 20 77  oke callback F w
333f0 69 74 68 20 66 69 72 73 74 0a 2a 2a 20 20 20 20  ith first.**    
33400 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20        parameter 
33410 50 20 77 68 65 6e 65 76 65 72 20 69 74 20 6e 65  P whenever it ne
33420 65 64 73 20 61 20 63 6f 6d 70 61 72 69 73 6f 6e  eds a comparison
33430 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 61 0a   function for a.
33440 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c  **          coll
33450 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20 74  ating sequence t
33460 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  hat it does not 
33470 6b 6e 6f 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a  know about..**.*
33480 2a 20 7b 46 31 36 37 30 34 7d 20 45 61 63 68 20  * {F16704} Each 
33490 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
334a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  to [sqlite3_coll
334b0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
334c0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
334d0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
334e0 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 20 6f 76  n_needed16()] ov
334f0 65 72 72 69 64 65 73 20 74 68 65 20 63 61 6c 6c  errides the call
33500 62 61 63 6b 20 72 65 67 69 73 74 65 72 65 64 0a  back registered.
33510 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74  **          on t
33520 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
33530 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62 79  e connection] by
33540 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20   prior calls to 
33550 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
33560 20 20 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a     interface..**
33570 0a 2a 2a 20 7b 46 31 36 37 30 36 7d 20 54 68 65  .** {F16706} The
33580 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 72 65 71   name of the req
33590 75 65 73 74 65 64 20 63 6f 6c 6c 61 74 69 6e 67  uested collating
335a0 20 66 75 6e 63 74 69 6f 6e 20 70 61 73 73 65 64   function passed
335b0 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   in the.**      
335c0 20 20 20 20 34 74 68 20 70 61 72 61 6d 65 74 65      4th paramete
335d0 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
335e0 6b 20 69 73 20 69 6e 20 55 54 46 2d 38 20 69 66  k is in UTF-8 if
335f0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
33600 20 20 20 20 20 20 20 20 20 20 77 61 73 20 72 65            was re
33610 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b  gistered using [
33620 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
33630 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 0a  n_needed()] and.
33640 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69  **          is i
33650 6e 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  n UTF-16 native 
33660 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 74 68  byte order if th
33670 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 0a 2a  e callback was.*
33680 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73  *          regis
33690 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  tered using [sql
336a0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
336b0 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  eeded16()]..**.*
336c0 2a 20 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  * .*/.int sqlite
336d0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
336e0 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ed(.  sqlite3*, 
336f0 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69  .  void*, .  voi
33700 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
33710 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
33720 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b  ,const char*).);
33730 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
33740 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
33750 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
33760 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29  void*,.  void(*)
33770 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
33780 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
33790 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
337a0 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
337b0 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79  key for an encry
337c0 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20  pted database.  
337d0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f  This routine sho
337e0 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64  uld be.** called
337f0 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c   right after sql
33800 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a  ite3_open()..**.
33810 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
33820 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
33830 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
33840 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
33850 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
33860 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
33870 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c  lite3_key(.  sql
33880 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
33890 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
338a0 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
338b0 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
338c0 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
338d0 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
338e0 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
338f0 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79  * Change the key
33900 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   on an open data
33910 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75  base.  If the cu
33920 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69  rrent database i
33930 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74  s not.** encrypt
33940 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ed, this routine
33950 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74   will encrypt it
33960 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72  .  If pNew==0 or
33970 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a   nNew==0, the.**
33980 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63   database is dec
33990 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  rypted..**.** Th
339a0 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
339b0 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
339c0 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
339d0 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
339e0 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
339f0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
33a00 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  _rekey(.  sqlite
33a10 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
33a20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
33a30 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
33a40 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
33a50 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
33a60 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65  ey     /* The ne
33a70 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  w key */.);../*.
33a80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 53 75  ** CAPI3REF:  Su
33a90 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20  spend Execution 
33aa0 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65  For A Short Time
33ab0 20 7b 46 31 30 35 33 30 7d 0a 2a 2a 0a 2a 2a 20   {F10530}.**.** 
33ac0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  The sqlite3_slee
33ad0 70 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  p() function.** 
33ae0 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65  causes the curre
33af0 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73  nt thread to sus
33b00 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a  pend execution.*
33b10 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61  * for at least a
33b20 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
33b30 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65  seconds specifie
33b40 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74  d in its paramet
33b50 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  er..**.** If the
33b60 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
33b70 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f  m does not suppo
33b80 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74  rt sleep request
33b90 73 20 77 69 74 68 20 0a 2a 2a 20 6d 69 6c 6c 69  s with .** milli
33ba0 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f  second time reso
33bb0 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  lution, then the
33bc0 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f   time will be ro
33bd0 75 6e 64 65 64 20 75 70 20 74 6f 20 0a 2a 2a 20  unded up to .** 
33be0 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f  the nearest seco
33bf0 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  nd. The number o
33c00 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  f milliseconds o
33c10 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
33c20 20 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66   .** requested f
33c30 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e  rom the operatin
33c40 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75  g system is retu
33c50 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rned..**.** SQLi
33c60 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
33c70 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  is interface by 
33c80 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65  calling the xSle
33c90 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  ep().** method o
33ca0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
33cb0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
33cc0 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ct..**.** INVARI
33cd0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  ANTS:.**.** {F10
33ce0 35 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  533} The [sqlite
33cf0 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65  3_sleep(M)] inte
33d00 72 66 61 63 65 20 69 6e 76 6f 6b 65 73 20 74 68  rface invokes th
33d10 65 20 78 53 6c 65 65 70 0a 2a 2a 20 20 20 20 20  e xSleep.**     
33d20 20 20 20 20 20 6d 65 74 68 6f 64 20 6f 66 20 74       method of t
33d30 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
33d40 74 65 33 5f 76 66 73 7c 56 46 53 5d 20 69 6e 20  te3_vfs|VFS] in 
33d50 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20  order to.**     
33d60 20 20 20 20 20 73 75 73 70 65 6e 64 20 65 78 65       suspend exe
33d70 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75  cution of the cu
33d80 72 72 65 6e 74 20 74 68 72 65 61 64 20 66 6f 72  rrent thread for
33d90 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 20 20 20   at least.**    
33da0 20 20 20 20 20 20 4d 20 6d 69 6c 6c 69 73 65 63        M millisec
33db0 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  onds..**.** {F10
33dc0 35 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  536} The [sqlite
33dd0 33 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65  3_sleep(M)] inte
33de0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
33df0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20  e number of.**  
33e00 20 20 20 20 20 20 20 20 6d 69 6c 6c 69 73 65 63          millisec
33e10 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63  onds of sleep ac
33e20 74 75 61 6c 6c 79 20 72 65 71 75 65 73 74 65 64  tually requested
33e30 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e   of the operatin
33e40 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 79  g.**          sy
33e50 73 74 65 6d 2c 20 77 68 69 63 68 20 6d 69 67 68  stem, which migh
33e60 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  t be larger than
33e70 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4d   the parameter M
33e80 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
33e90 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a  _sleep(int);../*
33ea0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 4e  .** CAPI3REF:  N
33eb0 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
33ec0 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72  r Holding Tempor
33ed0 61 72 79 20 46 69 6c 65 73 20 7b 46 31 30 33 31  ary Files {F1031
33ee0 30 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73  0}.**.** If this
33ef0 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
33f00 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
33f10 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  t to a string wh
33f20 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61  ich is.** the na
33f30 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28  me of a folder (
33f40 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79  a.k.a. directory
33f50 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70  ), then all temp
33f60 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63  orary files.** c
33f70 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  reated by SQLite
33f80 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20   will be placed 
33f90 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72  in that director
33fa0 79 2e 20 20 49 66 20 74 68 69 73 20 76 61 72 69  y.  If this vari
33fb0 61 62 6c 65 0a 2a 2a 20 69 73 20 4e 55 4c 4c 20  able.** is NULL 
33fc0 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
33fd0 4c 69 74 65 20 64 6f 65 73 20 61 20 73 65 61 72  Lite does a sear
33fe0 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70  ch for an approp
33ff0 72 69 61 74 65 20 74 65 6d 70 6f 72 61 72 79 0a  riate temporary.
34000 2a 2a 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72  ** file director
34010 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e  y..**.** It is n
34020 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f 64 69 66  ot safe to modif
34030 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  y this variable 
34040 6f 6e 63 65 20 61 20 64 61 74 61 62 61 73 65 20  once a database 
34050 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 68 61  connection.** ha
34060 73 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 20  s been opened.  
34070 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  It is intended t
34080 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
34090 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a  e be set once.**
340a0 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63   as part of proc
340b0 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
340c0 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e  on and before an
340d0 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
340e0 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68  ce.** routines h
340f0 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 20 61 6e  ave been call an
34100 64 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67  d remain unchang
34110 65 64 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a  ed thereafter..*
34120 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
34130 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65  char *sqlite3_te
34140 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f  mp_directory;../
34150 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20  *.** CAPI3REF:  
34160 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
34170 68 65 20 44 61 74 61 62 61 73 65 20 49 73 20 49  he Database Is I
34180 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f  n Auto-Commit Mo
34190 64 65 20 7b 46 31 32 39 33 30 7d 0a 2a 2a 0a 2a  de {F12930}.**.*
341a0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
341b0 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69  t_autocommit() i
341c0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
341d0 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20   non-zero or.** 
341e0 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65  zero if the give
341f0 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
34200 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e  ction is or is n
34210 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74  ot in autocommit
34220 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63   mode,.** respec
34230 74 69 76 65 6c 79 2e 20 20 20 41 75 74 6f 63 6f  tively.   Autoco
34240 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 0a  mmit mode is on.
34250 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  ** by default.  
34260 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
34270 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61  is disabled by a
34280 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65   [BEGIN] stateme
34290 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69  nt..** Autocommi
342a0 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61  t mode is re-ena
342b0 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49  bled by a [COMMI
342c0 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d  T] or [ROLLBACK]
342d0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61  ..**.** If certa
342e0 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f  in kinds of erro
342f0 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74  rs occur on a st
34300 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
34310 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74   multi-statement
34320 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  .** transactions
34330 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69   (errors includi
34340 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d  ng [SQLITE_FULL]
34350 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  , [SQLITE_IOERR]
34360 2c 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  , .** [SQLITE_NO
34370 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55  MEM], [SQLITE_BU
34380 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45  SY], and [SQLITE
34390 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65  _INTERRUPT]) the
343a0 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63  n the.** transac
343b0 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f  tion might be ro
343c0 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
343d0 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e  tically.  The on
343e0 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e  ly way to.** fin
343f0 64 20 6f 75 74 20 69 66 20 53 51 4c 69 74 65 20  d out if SQLite 
34400 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
34410 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 72  lled back the tr
34420 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a  ansaction after.
34430 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74  ** an error is t
34440 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 74  o use this funct
34450 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ion..**.** INVAR
34460 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
34470 32 39 33 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2931} The [sqlit
34480 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
34490 74 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(D)] interface 
344a0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
344b0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
344c0 7a 65 72 6f 20 69 66 20 74 68 65 20 5b 64 61 74  zero if the [dat
344d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
344e0 5d 20 44 20 69 73 20 6f 72 20 69 73 20 6e 6f 74  ] D is or is not
344f0 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a   in autocommit.*
34500 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 64 65 2c  *          mode,
34510 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
34520 2a 0a 2a 2a 20 7b 46 31 32 39 33 32 7d 20 41 75  *.** {F12932} Au
34530 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
34540 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a   on by default..
34550 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 33 7d 20 41  **.** {F12933} A
34560 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
34570 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20  s disabled by a 
34580 73 75 63 63 65 73 73 66 75 6c 20 5b 42 45 47 49  successful [BEGI
34590 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  N] statement..**
345a0 0a 2a 2a 20 7b 46 31 32 39 33 34 7d 20 41 75 74  .** {F12934} Aut
345b0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
345c0 65 6e 61 62 6c 65 64 20 62 79 20 61 20 73 75 63  enabled by a suc
345d0 63 65 73 73 66 75 6c 20 5b 43 4f 4d 4d 49 54 5d  cessful [COMMIT]
345e0 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 0a 2a   or [ROLLBACK].*
345f0 2a 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65  *          state
34600 6d 65 6e 74 2e 0a 2a 2a 20 0a 2a 2a 0a 2a 2a 20  ment..** .**.** 
34610 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 2a  LIMITATIONS:.***
34620 0a 2a 2a 20 7b 55 31 32 39 33 36 7d 20 49 66 20  .** {U12936} If 
34630 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63  another thread c
34640 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63  hanges the autoc
34650 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20  ommit status of 
34660 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
34670 20 20 20 20 20 20 20 20 20 63 6f 6e 6e 65 63 74           connect
34680 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72  ion while this r
34690 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e  outine is runnin
346a0 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  g, then the retu
346b0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20  rn value.**     
346c0 20 20 20 20 20 69 73 20 75 6e 64 65 66 69 6e 65       is undefine
346d0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
346e0 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
346f0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
34700 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 46 69  ** CAPI3REF:  Fi
34710 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65 20  nd The Database 
34720 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70  Handle Of A Prep
34730 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b  ared Statement {
34740 46 31 33 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F13120}.**.** Th
34750 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e  e sqlite3_db_han
34760 64 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  dle interface.**
34770 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 73 71   returns the [sq
34780 6c 69 74 65 33 2a 5d 20 64 61 74 61 62 61 73 65  lite3*] database
34790 20 68 61 6e 64 6c 65 20 74 6f 20 77 68 69 63 68   handle to which
347a0 20 61 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20   a.** [prepared 
347b0 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e  statement] belon
347c0 67 73 2e 0a 2a 2a 20 54 68 65 20 64 61 74 61 62  gs..** The datab
347d0 61 73 65 20 68 61 6e 64 6c 65 20 72 65 74 75 72  ase handle retur
347e0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64  ned by sqlite3_d
347f0 62 5f 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 74  b_handle.** is t
34800 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
34810 20 68 61 6e 64 6c 65 20 74 68 61 74 20 77 61 73   handle that was
34820 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 61 72  .** the first ar
34830 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
34840 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
34850 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  2()] or its vari
34860 61 6e 74 73 0a 2a 2a 20 74 68 61 74 20 77 61 73  ants.** that was
34870 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
34880 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  the statement in
34890 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65   the first place
348a0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
348b0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 32  TS:.**.** {F1312
348c0 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
348d0 64 62 5f 68 61 6e 64 6c 65 28 53 29 5d 20 69 6e  db_handle(S)] in
348e0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
348f0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20  a pointer.**    
34900 20 20 20 20 20 20 74 6f 20 74 68 65 20 5b 64 61        to the [da
34910 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34920 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  n] associated wi
34930 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  th.**          [
34940 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34950 6e 74 5d 20 53 2e 0a 2a 2f 0a 73 71 6c 69 74 65  nt] S..*/.sqlite
34960 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  3 *sqlite3_db_ha
34970 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndle(sqlite3_stm
34980 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
34990 33 52 45 46 3a 20 20 46 69 6e 64 20 74 68 65 20  3REF:  Find the 
349a0 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74  next prepared st
349b0 61 74 65 6d 65 6e 74 20 7b 46 31 33 31 34 30 7d  atement {F13140}
349c0 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 61 20  .**.** Return a 
349d0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e  pointer to the n
349e0 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74  ext [prepared st
349f0 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 20 70  atement] after p
34a00 53 74 6d 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74  Stmt.** associat
34a10 65 64 20 77 69 74 68 20 5b 64 61 74 61 62 61 73  ed with [databas
34a20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44  e connection] pD
34a30 62 2e 20 20 49 66 20 70 53 74 6d 74 20 69 73 20  b.  If pStmt is 
34a40 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 72 65 74  NULL.** then ret
34a50 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  urn a pointer to
34a60 20 74 68 65 20 66 69 72 73 74 20 5b 70 72 65 70   the first [prep
34a70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
34a80 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
34a90 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
34aa0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62   connection] pDb
34ab0 2e 20 20 49 66 20 6e 6f 20 5b 70 72 65 70 61 72  .  If no [prepar
34ac0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
34ad0 20 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63   satisfies the c
34ae0 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69  onditions of thi
34af0 73 20 72 6f 75 74 69 6e 65 2c 20 72 65 74 75 72  s routine, retur
34b00 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e  n NULL..**.** IN
34b10 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
34b20 7b 46 31 33 31 34 33 7d 20 49 66 20 44 20 69 73  {F13143} If D is
34b30 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
34b40 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 68 6f  nection] that ho
34b50 6c 64 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  lds one or more.
34b60 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e 66 69  **          unfi
34b70 6e 61 6c 69 7a 65 64 20 5b 70 72 65 70 61 72 65  nalized [prepare
34b80 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e  d statements] an
34b90 64 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  d S is a NULL po
34ba0 69 6e 74 65 72 2c 0a 2a 2a 20 20 20 20 20 20 20  inter,.**       
34bb0 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33     then [sqlite3
34bc0 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29  _next_stmt(D, S)
34bd0 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20  ] routine shall 
34be0 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72  return a pointer
34bf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
34c00 6f 6e 65 20 6f 66 20 74 68 65 20 5b 70 72 65 70  one of the [prep
34c10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
34c20 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
34c30 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 34   D..**.** {F1314
34c40 36 7d 20 49 66 20 44 20 69 73 20 61 20 5b 64 61  6} If D is a [da
34c50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34c60 6e 5d 20 74 68 61 74 20 68 6f 6c 64 73 20 6e 6f  n] that holds no
34c70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e 66  .**          unf
34c80 69 6e 61 6c 69 7a 65 64 20 5b 70 72 65 70 61 72  inalized [prepar
34c90 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 61  ed statements] a
34ca0 6e 64 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  nd S is a NULL p
34cb0 6f 69 6e 74 65 72 2c 0a 2a 2a 20 20 20 20 20 20  ointer,.**      
34cc0 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65      then [sqlite
34cd0 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53  3_next_stmt(D, S
34ce0 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c  )] routine shall
34cf0 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 0a 2a   return a NULL.*
34d00 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
34d10 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 34  er..**.** {F1314
34d20 39 7d 20 49 66 20 53 20 69 73 20 61 20 5b 70 72  9} If S is a [pr
34d30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
34d40 5d 20 69 6e 20 5b 64 61 74 61 62 61 73 65 20 63  ] in [database c
34d50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
34d60 20 20 20 20 20 20 20 20 20 61 6e 64 20 53 20 69           and S i
34d70 73 20 6e 6f 74 20 74 68 65 20 6c 61 73 74 20 5b  s not the last [
34d80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34d90 6e 74 5d 20 69 6e 20 44 2c 20 74 68 65 6e 0a 2a  nt] in D, then.*
34da0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
34db0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c  te3_next_stmt(D,
34dc0 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61   S)] routine sha
34dd0 6c 6c 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e  ll return a poin
34de0 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
34df0 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65  to the next [pre
34e00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
34e10 20 69 6e 20 44 20 61 66 74 65 72 20 53 2e 0a 2a   in D after S..*
34e20 2a 0a 2a 2a 20 7b 46 31 33 31 35 32 7d 20 49 66  *.** {F13152} If
34e30 20 53 20 69 73 20 74 68 65 20 6c 61 73 74 20 5b   S is the last [
34e40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34e50 6e 74 5d 20 69 6e 20 5b 64 61 74 61 62 61 73 65  nt] in [database
34e60 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
34e70 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
34e80 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
34e90 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e  mt(D, S)] routin
34ea0 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61  e shall return a
34eb0 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20   NULL.**        
34ec0 20 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2f    pointer..**.*/
34ed0 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73  .sqlite3_stmt *s
34ee0 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
34ef0 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73  (sqlite3 *pDb, s
34f00 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
34f10 6d 74 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt);.../*.** CAP
34f20 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e  I3REF: Commit An
34f30 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66  d Rollback Notif
34f40 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
34f50 73 20 7b 46 31 32 39 35 30 7d 0a 2a 2a 0a 2a 2a  s {F12950}.**.**
34f60 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d   The sqlite3_com
34f70 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  mit_hook() inter
34f80 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
34f90 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
34fa0 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
34fb0 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
34fc0 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f  ransaction is co
34fd0 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20  mmitted..** Any 
34fe0 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
34ff0 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
35000 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  to sqlite3_commi
35010 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20  t_hook().** for 
35020 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
35030 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
35040 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54  overridden..** T
35050 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  he sqlite3_rollb
35060 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ack_hook() inter
35070 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
35080 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
35090 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
350a0 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
350b0 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f  ransaction is co
350c0 6d 6d 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20  mmitted..** Any 
350d0 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
350e0 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
350f0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  to sqlite3_commi
35100 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20  t_hook().** for 
35110 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
35120 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
35130 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54  overridden..** T
35140 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
35150 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
35160 67 68 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  gh.** to the cal
35170 6c 62 61 63 6b 2e 20 20 49 66 20 74 68 65 20 63  lback.  If the c
35180 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d  allback on a com
35190 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f  mit hook functio
351a0 6e 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f  n .** returns no
351b0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
351c0 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65   commit is conve
351d0 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c  rted into a roll
351e0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  back..**.** If a
351f0 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20  nother function 
35200 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72  was previously r
35210 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 0a 2a  egistered, its.*
35220 2a 20 70 41 72 67 20 76 61 6c 75 65 20 69 73 20  * pArg value is 
35230 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
35240 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74  wise NULL is ret
35250 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  urned..**.** Reg
35260 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20  istering a NULL 
35270 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65  function disable
35280 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a  s the callback..
35290 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75  **.** For the pu
352a0 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41  rposes of this A
352b0 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f  PI, a transactio
352c0 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76  n is said to hav
352d0 65 20 62 65 65 6e 20 0a 2a 2a 20 72 6f 6c 6c 65  e been .** rolle
352e0 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70  d back if an exp
352f0 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22  licit "ROLLBACK"
35300 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78   statement is ex
35310 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e  ecuted, or.** an
35320 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72   error or constr
35330 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69  aint causes an i
35340 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b  mplicit rollback
35350 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68   to occur..** Th
35360 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62  e rollback callb
35370 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
35380 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
35390 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  ion is.** automa
353a0 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
353b0 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20  ack because the 
353c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
353d0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
353e0 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63  * The rollback c
353f0 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69  allback is not i
35400 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e  nvoked if a tran
35410 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f  saction is.** ro
35420 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73  lled back becaus
35430 65 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62  e a commit callb
35440 61 63 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e  ack returned non
35450 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e  -zero..** <todo>
35460 20 43 68 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c   Check on this <
35470 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  /todo>.**.** The
35480 73 65 20 61 72 65 20 65 78 70 65 72 69 6d 65 6e  se are experimen
35490 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
354a0 6e 64 20 61 72 65 20 73 75 62 6a 65 63 74 20 74  nd are subject t
354b0 6f 20 63 68 61 6e 67 65 2e 0a 2a 2a 0a 2a 2a 20  o change..**.** 
354c0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
354d0 2a 20 7b 46 31 32 39 35 31 7d 20 54 68 65 20 5b  * {F12951} The [
354e0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
354f0 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65  ook(D,F,P)] inte
35500 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
35510 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
35520 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
35530 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  n F to be invoke
35540 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  d with argument 
35550 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20  P whenever.**   
35560 20 20 20 20 20 20 20 61 20 74 72 61 6e 73 61 63         a transac
35570 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 20 6f 6e 20  tion commits on 
35580 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
35590 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
355a0 46 31 32 39 35 32 7d 20 54 68 65 20 5b 73 71 6c  F12952} The [sql
355b0 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
355c0 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61  (D,F,P)] interfa
355d0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 50  ce returns the P
355e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 67  .**          arg
355f0 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
35600 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74  revious call wit
35610 68 20 74 68 65 20 73 61 6d 65 20 0a 2a 2a 20 20  h the same .**  
35620 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
35630 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 5d 20 44  e connection ] D
35640 20 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68   , or NULL on th
35650 65 20 66 69 72 73 74 20 63 61 6c 6c 0a 2a 2a 20  e first call.** 
35660 20 20 20 20 20 20 20 20 20 66 6f 72 20 61 20 70           for a p
35670 61 72 74 69 63 75 6c 61 72 20 5b 64 61 74 61 62  articular [datab
35680 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
35690 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 33  D..**.** {F12953
356a0 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b  } Each call to [
356b0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
356c0 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69 74 65  ook()] overwrite
356d0 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
356e0 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73  *          regis
356f0 74 65 72 65 64 20 62 79 20 70 72 69 6f 72 20 63  tered by prior c
35700 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  alls..**.** {F12
35710 39 35 34 7d 20 49 66 20 74 68 65 20 46 20 61 72  954} If the F ar
35720 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
35730 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44  e3_commit_hook(D
35740 2c 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a  ,F,P)] is NULL.*
35750 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
35760 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20  the commit hook 
35770 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63  callback is canc
35780 65 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c  eled and no call
35790 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
357a0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
357b0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63   a transaction c
357c0 6f 6d 6d 69 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ommits..**.** {F
357d0 31 32 39 35 35 7d 20 49 66 20 74 68 65 20 63 6f  12955} If the co
357e0 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65  mmit callback re
357f0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 74  turns non-zero t
35800 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69  hen the commit i
35810 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  s.**          co
35820 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72  nverted into a r
35830 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b  ollback..**.** {
35840 46 31 32 39 36 31 7d 20 54 68 65 20 5b 73 71 6c  F12961} The [sql
35850 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
35860 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72  ok(D,F,P)] inter
35870 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 74  face registers t
35880 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  he.**          c
35890 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
358a0 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   F to be invoked
358b0 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50   with argument P
358c0 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20   whenever.**    
358d0 20 20 20 20 20 20 61 20 74 72 61 6e 73 61 63 74        a transact
358e0 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 20 6f  ion rolls back o
358f0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
35900 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
35910 20 7b 46 31 32 39 36 32 7d 20 54 68 65 20 5b 73   {F12962} The [s
35920 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
35930 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
35940 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
35950 68 65 20 50 0a 2a 2a 20 20 20 20 20 20 20 20 20  he P.**         
35960 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74   argument from t
35970 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
35980 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 0a   with the same .
35990 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
359a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
359b0 20 5d 20 44 20 2c 20 6f 72 20 4e 55 4c 4c 20 6f   ] D , or NULL o
359c0 6e 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  n the first call
359d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72  .**          for
359e0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 5b 64   a particular [d
359f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35a00 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  on] D..**.** {F1
35a10 32 39 36 33 7d 20 45 61 63 68 20 63 61 6c 6c 20  2963} Each call 
35a20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  to [sqlite3_roll
35a30 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65  back_hook()] ove
35a40 72 77 72 69 74 65 73 20 74 68 65 20 63 61 6c 6c  rwrites the call
35a50 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
35a60 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 70   registered by p
35a70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a  rior calls..**.*
35a80 2a 20 7b 46 31 32 39 36 34 7d 20 49 66 20 74 68  * {F12964} If th
35a90 65 20 46 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  e F argument to 
35aa0 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  [sqlite3_rollbac
35ab0 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  k_hook(D,F,P)] i
35ac0 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20  s NULL.**       
35ad0 20 20 20 74 68 65 6e 20 74 68 65 20 72 6f 6c 6c     then the roll
35ae0 62 61 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62 61  back hook callba
35af0 63 6b 20 69 73 20 63 61 6e 63 65 6c 65 64 20 61  ck is canceled a
35b00 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a  nd no callback.*
35b10 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e  *          is in
35b20 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 74 72 61  voked when a tra
35b30 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62  nsaction rolls b
35b40 61 63 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ack..*/.void *sq
35b50 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
35b60 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  k(sqlite3*, int(
35b70 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
35b80 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
35b90 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73  _rollback_hook(s
35ba0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29  qlite3*, void(*)
35bb0 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29  (void *), void*)
35bc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35bd0 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e  F: Data Change N
35be0 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
35bf0 62 61 63 6b 73 20 7b 46 31 32 39 37 30 7d 0a 2a  backs {F12970}.*
35c00 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
35c10 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69  _update_hook() i
35c20 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 67 69  nterface.** regi
35c30 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
35c40 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
35c50 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
35c60 65 63 74 69 6f 6e 20 69 64 65 6e 74 69 66 69 65  ection identifie
35c70 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 72  d by the .** fir
35c80 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 62  st argument to b
35c90 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
35ca0 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61  er a row is upda
35cb0 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ted, inserted or
35cc0 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79   deleted..** Any
35cd0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
35ce0 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
35cf0 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
35d00 6e 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 0a  n for the same .
35d10 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
35d20 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
35d30 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dden..**.** The 
35d40 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
35d50 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
35d60 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  the function to 
35d70 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 20 0a 2a  invoke when a .*
35d80 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64  * row is updated
35d90 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  , inserted or de
35da0 6c 65 74 65 64 2e 20 0a 2a 2a 20 54 68 65 20 66  leted. .** The f
35db0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
35dc0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
35dd0 0a 2a 2a 20 61 20 63 6f 70 79 20 6f 66 20 74 68  .** a copy of th
35de0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
35df0 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61   to sqlite3_upda
35e00 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68  te_hook()..** Th
35e10 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63  e second callbac
35e20 6b 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  k .** argument i
35e30 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
35e40 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54  _INSERT], [SQLIT
35e50 45 5f 44 45 4c 45 54 45 5d 20 6f 72 20 5b 53 51  E_DELETE] or [SQ
35e60 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a  LITE_UPDATE],.**
35e70 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
35e80 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  e operation that
35e90 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c   caused the call
35ea0 62 61 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b  back to be invok
35eb0 65 64 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64  ed..** The third
35ec0 20 61 6e 64 20 0a 2a 2a 20 66 6f 75 72 74 68 20   and .** fourth 
35ed0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
35ee0 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
35ef0 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  n pointers to th
35f00 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 0a  e database and .
35f10 2a 2a 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f  ** table name co
35f20 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66  ntaining the aff
35f30 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 68  ected row..** Th
35f40 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b  e final callback
35f50 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 0a 2a   parameter is .*
35f60 2a 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74  * the rowid of t
35f70 68 65 20 72 6f 77 2e 0a 2a 2a 20 49 6e 20 74 68  he row..** In th
35f80 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64  e case of an upd
35f90 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 65  ate, this is the
35fa0 20 72 6f 77 69 64 20 61 66 74 65 72 20 0a 2a 2a   rowid after .**
35fb0 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65   the update take
35fc0 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  s place..**.** T
35fd0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69  he update hook i
35fe0 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68  s not invoked wh
35ff0 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74  en internal syst
36000 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a  em tables are.**
36010 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20   modified (i.e. 
36020 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e  sqlite_master an
36030 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63  d sqlite_sequenc
36040 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f  e)..**.** If ano
36050 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61  ther function wa
36060 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  s previously reg
36070 69 73 74 65 72 65 64 2c 20 69 74 73 20 70 41 72  istered, its pAr
36080 67 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 72 65  g value.** is re
36090 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
360a0 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  se NULL is retur
360b0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ned..**.** INVAR
360c0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
360d0 32 39 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2971} The [sqlit
360e0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44  e3_update_hook(D
360f0 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
36100 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63 6b   causes callback
36110 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e  .**          fun
36120 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e  ction F to be in
36130 76 6f 6b 65 64 20 77 69 74 68 20 66 69 72 73 74  voked with first
36140 20 70 61 72 61 6d 65 74 65 72 20 50 20 77 68 65   parameter P whe
36150 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  never.**        
36160 20 20 61 20 74 61 62 6c 65 20 72 6f 77 20 69 73    a table row is
36170 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72   modified, inser
36180 74 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20  ted, or deleted 
36190 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  on.**          [
361a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
361b0 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ion] D..**.** {F
361c0 31 32 39 37 33 7d 20 54 68 65 20 5b 73 71 6c 69  12973} The [sqli
361d0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
361e0 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63  D,F,P)] interfac
361f0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  e returns the va
36200 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lue.**          
36210 6f 66 20 50 20 66 6f 72 20 74 68 65 20 70 72 65  of P for the pre
36220 76 69 6f 75 73 20 63 61 6c 6c 20 6f 6e 20 74 68  vious call on th
36230 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
36240 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a   connection] D,.
36250 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e  **          or N
36260 55 4c 4c 20 66 6f 72 20 74 68 65 20 66 69 72 73  ULL for the firs
36270 74 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46  t call..**.** {F
36280 31 32 39 37 35 7d 20 49 66 20 74 68 65 20 75 70  12975} If the up
36290 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61  date hook callba
362a0 63 6b 20 46 20 69 6e 20 5b 73 71 6c 69 74 65 33  ck F in [sqlite3
362b0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46  _update_hook(D,F
362c0 2c 50 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,P)].**         
362d0 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68   is NULL then th
362e0 65 20 6e 6f 20 75 70 64 61 74 65 20 63 61 6c 6c  e no update call
362f0 62 61 63 6b 73 20 61 72 65 20 6d 61 64 65 2e 0a  backs are made..
36300 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 37 7d 20 45  **.** {F12977} E
36310 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ach call to [sql
36320 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
36330 28 44 2c 46 2c 50 29 5d 20 6f 76 65 72 72 69 64  (D,F,P)] overrid
36340 65 73 20 70 72 69 6f 72 20 63 61 6c 6c 73 0a 2a  es prior calls.*
36350 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68  *          to th
36360 65 20 73 61 6d 65 20 69 6e 74 65 72 66 61 63 65  e same interface
36370 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
36380 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36390 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  n] D..**.** {F12
363a0 39 37 39 7d 20 54 68 65 20 75 70 64 61 74 65 20  979} The update 
363b0 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  hook callback is
363c0 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65   not invoked whe
363d0 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65  n internal syste
363e0 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 61  m.**          ta
363f0 62 6c 65 73 20 73 75 63 68 20 61 73 20 73 71 6c  bles such as sql
36400 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73  ite_master and s
36410 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 20 61  qlite_sequence a
36420 72 65 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  re modified..**.
36430 2a 2a 20 7b 46 31 32 39 38 31 7d 20 54 68 65 20  ** {F12981} The 
36440 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
36450 20 74 6f 20 74 68 65 20 75 70 64 61 74 65 20 63   to the update c
36460 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20 20 20 20 20  allback .**     
36470 20 20 20 20 20 69 73 20 6f 6e 65 20 6f 66 20 5b       is one of [
36480 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20  SQLITE_INSERT], 
36490 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
364a0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54  or [SQLITE_UPDAT
364b0 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  E],.**          
364c0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
364d0 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
364e0 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62  caused the callb
364f0 61 63 6b 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ack to be invoke
36500 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 33  d..**.** {F12983
36510 7d 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20  } The third and 
36520 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
36530 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
36540 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
36550 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  s.**          to
36560 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
36570 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 20 77   UTF-8 strings w
36580 68 69 63 68 20 61 72 65 20 74 68 65 20 6e 61 6d  hich are the nam
36590 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  es of the.**    
365a0 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20 61        database a
365b0 6e 64 20 74 61 62 6c 65 20 74 68 61 74 20 69 73  nd table that is
365c0 20 62 65 69 6e 67 20 75 70 64 61 74 65 64 2e 0a   being updated..
365d0 0a 2a 2a 20 7b 46 31 32 39 38 35 7d 20 54 68 65  .** {F12985} The
365e0 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20   final callback 
365f0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
36600 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f   rowid of the ro
36610 77 20 61 66 74 65 72 0a 2a 2a 20 20 20 20 20 20  w after.**      
36620 20 20 20 20 74 68 65 20 63 68 61 6e 67 65 20 6f      the change o
36630 63 63 75 72 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  ccurs..*/.void *
36640 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
36650 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ook(.  sqlite3*,
36660 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
36670 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e   *,int ,char con
36680 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20  st *,char const 
36690 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
366a0 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a  ,.  void*.);../*
366b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45  .** CAPI3REF:  E
366c0 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
366d0 20 53 68 61 72 65 64 20 50 61 67 65 72 20 43 61   Shared Pager Ca
366e0 63 68 65 20 7b 46 31 30 33 33 30 7d 0a 2a 2a 20  che {F10330}.** 
366f0 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65  KEYWORDS: {share
36700 64 20 63 61 63 68 65 7d 20 7b 73 68 61 72 65 64  d cache} {shared
36710 20 63 61 63 68 65 20 6d 6f 64 65 7d 0a 2a 2a 0a   cache mode}.**.
36720 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
36730 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
36740 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20  les the sharing 
36750 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
36760 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68  cache.** and sch
36770 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75  ema data structu
36780 72 65 73 20 62 65 74 77 65 65 6e 20 63 6f 6e 6e  res between conn
36790 65 63 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 73  ections to the s
367a0 61 6d 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a  ame database..**
367b0 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62   Sharing is enab
367c0 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
367d0 65 6e 74 20 69 73 20 74 72 75 65 20 61 6e 64 20  ent is true and 
367e0 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20  disabled if the 
367f0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 66  argument.** is f
36800 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 63 68  alse..**.** Cach
36810 65 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61  e sharing is ena
36820 62 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65  bled and disable
36830 64 0a 2a 2a 20 66 6f 72 20 61 6e 20 65 6e 74 69  d.** for an enti
36840 72 65 20 70 72 6f 63 65 73 73 2e 20 7b 45 4e 44  re process. {END
36850 7d 20 54 68 69 73 20 69 73 20 61 20 63 68 61 6e  } This is a chan
36860 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20  ge as of SQLite 
36870 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 0a 2a  version 3.5.0..*
36880 2a 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69  * In prior versi
36890 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 20 73  ons of SQLite, s
368a0 68 61 72 69 6e 67 20 77 61 73 0a 2a 2a 20 65 6e  haring was.** en
368b0 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
368c0 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61  d for each threa
368d0 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  d separately..**
368e0 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 20 73 68  .** The cache sh
368f0 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62  aring mode set b
36900 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  y this interface
36910 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62   effects all sub
36920 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
36930 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
36940 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
36950 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b  pen_v2()], and [
36960 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
36970 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64  ]..** Existing d
36980 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36990 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65  ons continue use
369a0 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64   the sharing mod
369b0 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e  e.** that was in
369c0 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74   effect at the t
369d0 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70  ime they were op
369e0 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74  ened..**.** Virt
369f0 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e 6f  ual tables canno
36a00 74 20 62 65 20 75 73 65 64 20 77 69 74 68 20 61  t be used with a
36a10 20 73 68 61 72 65 64 20 63 61 63 68 65 2e 20 20   shared cache.  
36a20 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20   When shared.** 
36a30 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
36a40 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  , the [sqlite3_c
36a50 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20  reate_module()] 
36a60 41 50 49 20 75 73 65 64 20 74 6f 20 72 65 67 69  API used to regi
36a70 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20  ster.** virtual 
36a80 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61  tables will alwa
36a90 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  ys return an err
36aa0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  or..**.** This r
36ab0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
36ac0 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68  SQLITE_OK] if sh
36ad0 61 72 65 64 20 63 61 63 68 65 20 77 61 73 0a 2a  ared cache was.*
36ae0 2a 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  * enabled or dis
36af0 61 62 6c 65 64 20 73 75 63 63 65 73 73 66 75 6c  abled successful
36b00 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63  ly.  An [error c
36b10 6f 64 65 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ode].** is retur
36b20 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  ned otherwise..*
36b30 2a 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68  *.** Shared cach
36b40 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
36b50 20 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68   default. But th
36b60 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  is might change 
36b70 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c  in.** future rel
36b80 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
36b90 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
36ba0 68 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73  hat care about s
36bb0 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73  hared.** cache s
36bc0 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65  etting should se
36bd0 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e  t it explicitly.
36be0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
36bf0 53 3a 0a 2a 2a 20 0a 2a 2a 20 7b 46 31 30 33 33  S:.** .** {F1033
36c00 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  1} A successful 
36c10 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
36c20 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
36c30 61 72 65 64 5f 63 61 63 68 65 28 42 29 5d 0a 2a  ared_cache(B)].*
36c40 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20  *          will 
36c50 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
36c60 65 20 73 68 61 72 65 64 20 63 61 63 68 65 20 6d  e shared cache m
36c70 6f 64 65 20 66 6f 72 20 61 6e 79 20 73 75 62 73  ode for any subs
36c80 65 71 75 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20  equently.**     
36c90 20 20 20 20 20 63 72 65 61 74 65 64 20 5b 64 61       created [da
36ca0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36cb0 6e 5d 20 69 6e 20 74 68 65 20 73 61 6d 65 20 70  n] in the same p
36cc0 72 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  rocess..**.** {F
36cd0 31 30 33 33 36 7d 20 57 68 65 6e 20 73 68 61 72  10336} When shar
36ce0 65 64 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ed cache is enab
36cf0 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  led, the [sqlite
36d00 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
36d10 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
36d20 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 61 6c  nterface will al
36d30 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65  ways return an e
36d40 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  rror..**.** {F10
36d50 33 33 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  337} The [sqlite
36d60 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
36d70 63 61 63 68 65 28 42 29 5d 20 69 6e 74 65 72 66  cache(B)] interf
36d80 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ace returns.**  
36d90 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
36da0 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61  OK] if shared ca
36db0 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20  che was enabled 
36dc0 6f 72 20 64 69 73 61 62 6c 65 64 20 73 75 63 63  or disabled succ
36dd0 65 73 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  essfully..**.** 
36de0 7b 46 31 30 33 33 39 7d 20 53 68 61 72 65 64 20  {F10339} Shared 
36df0 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65  cache is disable
36e00 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2f  d by default..*/
36e10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61  .int sqlite3_ena
36e20 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
36e30 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
36e40 50 49 33 52 45 46 3a 20 20 41 74 74 65 6d 70 74  PI3REF:  Attempt
36e50 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65   To Free Heap Me
36e60 6d 6f 72 79 20 7b 46 31 37 33 34 30 7d 0a 2a 2a  mory {F17340}.**
36e70 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
36e80 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
36e90 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
36ea0 70 74 73 20 74 6f 0a 2a 2a 20 66 72 65 65 20 4e  pts to.** free N
36eb0 20 62 79 74 65 73 20 6f 66 20 68 65 61 70 20 6d   bytes of heap m
36ec0 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63  emory by dealloc
36ed0 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74  ating non-essent
36ee0 69 61 6c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ial memory.** al
36ef0 6c 6f 63 61 74 69 6f 6e 73 20 68 65 6c 64 20 62  locations held b
36f00 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c  y the database l
36f10 69 62 72 61 72 79 2e 20 7b 45 4e 44 7d 20 20 4d  ibrary. {END}  M
36f20 65 6d 6f 72 79 20 75 73 65 64 0a 2a 2a 20 74 6f  emory used.** to
36f30 20 63 61 63 68 65 20 64 61 74 61 62 61 73 65 20   cache database 
36f40 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65  pages to improve
36f50 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20   performance is 
36f60 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 0a 2a 2a  an example of.**
36f70 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d   non-essential m
36f80 65 6d 6f 72 79 2e 20 20 53 71 6c 69 74 65 33 5f  emory.  Sqlite3_
36f90 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
36fa0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
36fb0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
36fc0 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 20  actually freed, 
36fd0 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d  which might be m
36fe0 6f 72 65 20 6f 72 20 6c 65 73 73 0a 2a 2a 20 74  ore or less.** t
36ff0 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72  han the amount r
37000 65 71 75 65 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  equested..**.** 
37010 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
37020 2a 20 7b 46 31 37 33 34 31 7d 20 54 68 65 20 5b  * {F17341} The [
37030 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
37040 6d 65 6d 6f 72 79 28 4e 29 5d 20 69 6e 74 65 72  memory(N)] inter
37050 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
37060 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 65  .**          fre
37070 65 20 4e 20 62 79 74 65 73 20 6f 66 20 68 65 61  e N bytes of hea
37080 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c  p memory by deal
37090 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73  locating non-ess
370a0 65 6e 74 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20  ential.**       
370b0 20 20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61     memory alloca
370c0 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 20 74 68  tions held by th
370d0 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61  e database libra
370e0 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 34  ry..**.** {F1634
370f0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
37100 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 4e  release_memory(N
37110 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  )] returns the n
37120 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  umber.**        
37130 20 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 61    of bytes actua
37140 6c 6c 79 20 66 72 65 65 64 2c 20 77 68 69 63 68  lly freed, which
37150 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f   might be more o
37160 72 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20 20  r less.**       
37170 20 20 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75     than the amou
37180 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2f  nt requested..*/
37190 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c  .int sqlite3_rel
371a0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29  ease_memory(int)
371b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
371c0 46 3a 20 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d  F:  Impose A Lim
371d0 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 20  it On Heap Size 
371e0 7b 46 31 37 33 35 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F17350}.**.** T
371f0 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  he sqlite3_soft_
37200 68 65 61 70 5f 6c 69 6d 69 74 28 29 20 69 6e 74  heap_limit() int
37210 65 72 66 61 63 65 0a 2a 2a 20 70 6c 61 63 65 73  erface.** places
37220 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 20   a "soft" limit 
37230 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  on the amount of
37240 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61   heap memory tha
37250 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74  t may be allocat
37260 65 64 0a 2a 2a 20 62 79 20 53 51 4c 69 74 65 2e  ed.** by SQLite.
37270 20 49 66 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20   If an internal 
37280 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 72 65  allocation is re
37290 71 75 65 73 74 65 64 20 0a 2a 2a 20 74 68 61 74  quested .** that
372a0 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68   would exceed th
372b0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
372c0 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  t, [sqlite3_rele
372d0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 69 73  ase_memory()] is
372e0 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20  .** invoked one 
372f0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
37300 20 66 72 65 65 20 75 70 20 73 6f 6d 65 20 73 70   free up some sp
37310 61 63 65 20 62 65 66 6f 72 65 20 74 68 65 20 61  ace before the a
37320 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  llocation.** is 
37330 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  made..**.** The 
37340 6c 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20  limit is called 
37350 22 73 6f 66 74 22 2c 20 62 65 63 61 75 73 65 20  "soft", because 
37360 69 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  if.** [sqlite3_r
37370 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
37380 20 63 61 6e 6e 6f 74 0a 2a 2a 20 66 72 65 65 20   cannot.** free 
37390 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
373a0 79 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 65  y to prevent the
373b0 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62 65 69 6e   limit from bein
373c0 67 20 65 78 63 65 65 64 65 64 2c 0a 2a 2a 20 74  g exceeded,.** t
373d0 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 61 6c 6c  he memory is all
373e0 6f 63 61 74 65 64 20 61 6e 79 77 61 79 20 61 6e  ocated anyway an
373f0 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 6f 70  d the current op
37400 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
37410 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67 61 74 69  ..**.** A negati
37420 76 65 20 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65  ve or zero value
37430 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20 74 68 61   for N means tha
37440 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f  t there is no so
37450 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e  ft heap limit an
37460 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  d.** [sqlite3_re
37470 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20  lease_memory()] 
37480 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20 63 61 6c  will only be cal
37490 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20  led when memory 
374a0 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a  is exhausted..**
374b0 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
374c0 75 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20  ue for the soft 
374d0 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65  heap limit is ze
374e0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ro..**.** SQLite
374f0 20 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65 66   makes a best ef
37500 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68  fort to honor th
37510 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
37520 74 2e 20 20 0a 2a 2a 20 42 75 74 20 69 66 20 74  t.  .** But if t
37530 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
37540 69 74 20 63 61 6e 6e 6f 74 20 62 65 20 68 6f 6e  it cannot be hon
37550 6f 72 65 64 2c 20 65 78 65 63 75 74 69 6f 6e 20  ored, execution 
37560 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65  will.** continue
37570 20 77 69 74 68 6f 75 74 20 65 72 72 6f 72 20 6f   without error o
37580 72 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e 20  r notification. 
37590 20 54 68 69 73 20 69 73 20 77 68 79 20 74 68 65   This is why the
375a0 20 6c 69 6d 69 74 20 69 73 20 0a 2a 2a 20 63 61   limit is .** ca
375b0 6c 6c 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69  lled a "soft" li
375c0 6d 69 74 2e 20 20 49 74 20 69 73 20 61 64 76 69  mit.  It is advi
375d0 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  sory only..**.**
375e0 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65   Prior to SQLite
375f0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20   version 3.5.0, 
37600 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c  this routine onl
37610 79 20 63 6f 6e 73 74 72 61 69 6e 65 64 20 74 68  y constrained th
37620 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
37630 63 61 74 65 64 20 62 79 20 61 20 73 69 6e 67 6c  cated by a singl
37640 65 20 74 68 72 65 61 64 20 2d 20 74 68 65 20 73  e thread - the s
37650 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
37660 69 63 68 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ich this routine
37670 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65 67 69 6e  .** runs.  Begin
37680 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65  ning with SQLite
37690 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20   version 3.5.0, 
376a0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
376b0 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65  mit is.** applie
376c0 64 20 74 6f 20 61 6c 6c 20 74 68 72 65 61 64 73  d to all threads
376d0 2e 20 54 68 65 20 76 61 6c 75 65 20 73 70 65 63  . The value spec
376e0 69 66 69 65 64 20 66 6f 72 20 74 68 65 20 73 6f  ified for the so
376f0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a  ft heap limit.**
37700 20 69 73 20 61 6e 20 75 70 70 65 72 20 62 6f 75   is an upper bou
37710 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20  nd on the total 
37720 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
37730 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 61 64  n for all thread
37740 73 2e 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e  s. In.** version
37750 20 33 2e 35 2e 30 20 74 68 65 72 65 20 69 73 20   3.5.0 there is 
37760 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72  no mechanism for
37770 20 6c 69 6d 69 74 69 6e 67 20 74 68 65 20 68 65   limiting the he
37780 61 70 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20  ap usage for.** 
37790 69 6e 64 69 76 69 64 75 61 6c 20 74 68 72 65 61  individual threa
377a0 64 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ds..**.** INVARI
377b0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ANTS:.**.** {F16
377c0 33 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  351} The [sqlite
377d0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
377e0 74 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(N)] interface 
377f0 70 6c 61 63 65 73 20 61 20 73 6f 66 74 20 6c 69  places a soft li
37800 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  mit.**          
37810 6f 66 20 4e 20 62 79 74 65 73 20 6f 6e 20 74 68  of N bytes on th
37820 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70  e amount of heap
37830 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79   memory that may
37840 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a   be allocated.**
37850 20 20 20 20 20 20 20 20 20 20 75 73 69 6e 67 20            using 
37860 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
37870 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
37880 65 61 6c 6c 6f 63 28 29 5d 20 61 74 20 61 6e 79  ealloc()] at any
37890 20 70 6f 69 6e 74 0a 2a 2a 20 20 20 20 20 20 20   point.**       
378a0 20 20 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a     in time..**.*
378b0 2a 20 7b 46 31 36 33 35 32 7d 20 49 66 20 61 20  * {F16352} If a 
378c0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
378d0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
378e0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
378f0 5d 20 77 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 20  ] would.**      
37900 20 20 20 20 63 61 75 73 65 20 74 68 65 20 74 6f      cause the to
37910 74 61 6c 20 61 6d 6f 75 6e 74 20 6f 66 20 61 6c  tal amount of al
37920 6c 6f 63 61 74 65 64 20 6d 65 6d 6f 72 79 20 74  located memory t
37930 6f 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20  o exceed the.** 
37940 20 20 20 20 20 20 20 20 20 73 6f 66 74 20 68 65           soft he
37950 61 70 20 6c 69 6d 69 74 2c 20 74 68 65 6e 20 5b  ap limit, then [
37960 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
37970 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e 76  memory()] is inv
37980 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  oked.**         
37990 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74   in an attempt t
379a0 6f 20 72 65 64 75 63 65 20 74 68 65 20 6d 65 6d  o reduce the mem
379b0 6f 72 79 20 75 73 61 67 65 20 70 72 69 6f 72 20  ory usage prior 
379c0 74 6f 20 70 72 6f 63 65 65 64 69 6e 67 0a 2a 2a  to proceeding.**
379d0 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 74            with t
379e0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
379f0 74 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a 2a 2a  tion attempt..**
37a00 0a 2a 2a 20 7b 46 31 36 33 35 33 7d 20 43 61 6c  .** {F16353} Cal
37a10 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  ls to [sqlite3_m
37a20 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
37a30 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
37a40 74 68 61 74 20 74 72 69 67 67 65 72 0a 2a 2a 20  that trigger.** 
37a50 20 20 20 20 20 20 20 20 20 61 74 74 65 6d 70 74           attempt
37a60 73 20 74 6f 20 72 65 64 75 63 65 20 6d 65 6d 6f  s to reduce memo
37a70 72 79 20 75 73 61 67 65 20 74 68 72 6f 75 67 68  ry usage through
37a80 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
37a90 69 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  imit.**         
37aa0 20 6d 65 63 68 61 6e 69 73 6d 20 63 6f 6e 74 69   mechanism conti
37ab0 6e 75 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  nue even if the 
37ac0 61 74 74 65 6d 70 74 20 74 6f 20 72 65 64 75 63  attempt to reduc
37ad0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20  e memory.**     
37ae0 20 20 20 20 20 75 73 61 67 65 20 69 73 20 75 6e       usage is un
37af0 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2a 0a 2a  successful..**.*
37b00 2a 20 7b 46 31 36 33 35 34 7d 20 41 20 6e 65 67  * {F16354} A neg
37b10 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61  ative or zero va
37b20 6c 75 65 20 66 6f 72 20 4e 20 69 6e 20 61 20 63  lue for N in a c
37b30 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  all to.**       
37b40 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74     [sqlite3_soft
37b50 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20  _heap_limit(N)] 
37b60 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72 65  means that there
37b70 20 69 73 20 6e 6f 20 73 6f 66 74 0a 2a 2a 20 20   is no soft.**  
37b80 20 20 20 20 20 20 20 20 68 65 61 70 20 6c 69 6d          heap lim
37b90 69 74 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  it and [sqlite3_
37ba0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
37bb0 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 0a 2a  ] will only be.*
37bc0 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 65  *          calle
37bd0 64 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73  d when memory is
37be0 20 63 6f 6d 70 6c 65 74 65 6c 79 20 65 78 68 61   completely exha
37bf0 75 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  usted..**.** {F1
37c00 36 33 35 35 7d 20 54 68 65 20 64 65 66 61 75 6c  6355} The defaul
37c10 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  t value for the 
37c20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
37c30 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b  is zero..**.** {
37c40 46 31 36 33 35 38 7d 20 45 61 63 68 20 63 61 6c  F16358} Each cal
37c50 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 6f  l to [sqlite3_so
37c60 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e 29  ft_heap_limit(N)
37c70 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  ] overrides the.
37c80 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
37c90 65 73 20 73 65 74 20 62 79 20 61 6c 6c 20 70 72  es set by all pr
37ca0 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2f 0a 76 6f  ior calls..*/.vo
37cb0 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  id sqlite3_soft_
37cc0 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b  heap_limit(int);
37cd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37ce0 3a 20 20 45 78 74 72 61 63 74 20 4d 65 74 61 64  :  Extract Metad
37cf0 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75  ata About A Colu
37d00 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 20 7b 46  mn Of A Table {F
37d10 31 32 38 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69  12850}.**.** Thi
37d20 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 74  s routine.** ret
37d30 75 72 6e 73 20 6d 65 74 61 2d 64 61 74 61 20 61  urns meta-data a
37d40 62 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 20  bout a specific 
37d50 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63  column of a spec
37d60 69 66 69 63 20 64 61 74 61 62 61 73 65 0a 2a 2a  ific database.**
37d70 20 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c   table accessibl
37d80 65 20 75 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e  e using the conn
37d90 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 70 61  ection handle pa
37da0 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
37db0 74 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20 61  t function .** a
37dc0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
37dd0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65  he column is ide
37de0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73  ntified by the s
37df0 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64  econd, third and
37e00 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
37e10 72 73 20 74 6f 20 0a 2a 2a 20 74 68 69 73 20 66  rs to .** this f
37e20 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 73 65 63  unction. The sec
37e30 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
37e40 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65   either the name
37e50 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
37e60 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22  .** (i.e. "main"
37e70 2c 20 22 74 65 6d 70 22 20 6f 72 20 61 6e 20 61  , "temp" or an a
37e80 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
37e90 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
37ea0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61   specified.** ta
37eb0 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20  ble or NULL. If 
37ec0 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  it is NULL, then
37ed0 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61   all attached da
37ee0 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61 72  tabases are sear
37ef0 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ched.** for the 
37f00 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  table using the 
37f10 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 61  same algorithm a
37f20 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  s the database e
37f30 6e 67 69 6e 65 20 75 73 65 73 20 74 6f 20 0a 2a  ngine uses to .*
37f40 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c  * resolve unqual
37f50 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65  ified table refe
37f60 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  rences..**.** Th
37f70 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
37f80 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
37f90 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61   this function a
37fa0 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64  re the table and
37fb0 20 63 6f 6c 75 6d 6e 20 0a 2a 2a 20 6e 61 6d 65   column .** name
37fc0 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20   of the desired 
37fd0 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69  column, respecti
37fe0 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66  vely. Neither of
37ff0 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72   these parameter
38000 73 20 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  s .** may be NUL
38010 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 20 69 6e  L..**.** Meta in
38020 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 74  formation is ret
38030 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67  urned by writing
38040 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c   to the memory l
38050 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20  ocations passed 
38060 61 73 0a 2a 2a 20 74 68 65 20 35 74 68 20 61 6e  as.** the 5th an
38070 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72  d subsequent par
38080 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20  ameters to this 
38090 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20 6f 66  function. Any of
380a0 20 74 68 65 73 65 20 0a 2a 2a 20 61 72 67 75 6d   these .** argum
380b0 65 6e 74 73 20 6d 61 79 20 62 65 20 4e 55 4c 4c  ents may be NULL
380c0 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  , in which case 
380d0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
380e0 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74  g element of met
380f0 61 20 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  a .** informatio
38100 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  n is omitted..**
38110 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 50 61 72  .** <pre>.** Par
38120 61 6d 65 74 65 72 20 20 20 20 20 4f 75 74 70 75  ameter     Outpu
38130 74 20 54 79 70 65 20 20 20 20 20 20 44 65 73 63  t Type      Desc
38140 72 69 70 74 69 6f 6e 0a 2a 2a 20 2d 2d 2d 2d 2d  ription.** -----
38150 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
38160 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
38170 2a 0a 2a 2a 20 20 20 35 74 68 20 20 20 20 20 20  *.**   5th      
38180 20 20 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 20     const char*  
38190 20 20 20 20 44 61 74 61 20 74 79 70 65 0a 2a 2a      Data type.**
381a0 20 20 20 36 74 68 20 20 20 20 20 20 20 20 20 63     6th         c
381b0 6f 6e 73 74 20 63 68 61 72 2a 20 20 20 20 20 20  onst char*      
381c0 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 66 61  Name of the defa
381d0 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ult collation se
381e0 71 75 65 6e 63 65 20 0a 2a 2a 20 20 20 37 74 68  quence .**   7th
381f0 20 20 20 20 20 20 20 20 20 69 6e 74 20 20 20 20           int    
38200 20 20 20 20 20 20 20 20 20 20 54 72 75 65 20 69            True i
38210 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 68 61 73  f the column has
38220 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73   a NOT NULL cons
38230 74 72 61 69 6e 74 0a 2a 2a 20 20 20 38 74 68 20  traint.**   8th 
38240 20 20 20 20 20 20 20 20 69 6e 74 20 20 20 20 20          int     
38250 20 20 20 20 20 20 20 20 20 54 72 75 65 20 69 66           True if
38260 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 70   the column is p
38270 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41  art of the PRIMA
38280 52 59 20 4b 45 59 0a 2a 2a 20 20 20 39 74 68 20  RY KEY.**   9th 
38290 20 20 20 20 20 20 20 20 69 6e 74 20 20 20 20 20          int     
382a0 20 20 20 20 20 20 20 20 20 54 72 75 65 20 69 66           True if
382b0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 41   the column is A
382c0 55 54 4f 49 4e 43 52 45 4d 45 4e 54 0a 2a 2a 20  UTOINCREMENT.** 
382d0 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 0a 2a 2a 20  </pre>.**.**.** 
382e0 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  The memory point
382f0 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61  ed to by the cha
38300 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20  racter pointers 
38310 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65  returned for the
38320 20 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e   .** declaration
38330 20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74   type and collat
38340 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20  ion sequence is 
38350 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c  valid only until
38360 20 74 68 65 20 6e 65 78 74 20 0a 2a 2a 20 63 61   the next .** ca
38370 6c 6c 20 74 6f 20 61 6e 79 20 73 71 6c 69 74 65  ll to any sqlite
38380 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   API function..*
38390 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63  *.** If the spec
383a0 69 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 61  ified table is a
383b0 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20  ctually a view, 
383c0 74 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 69 73  then an error is
383d0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
383e0 20 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65   If the specifie
383f0 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77  d column is "row
38400 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f  id", "oid" or "_
38410 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 20 0a  rowid_" and an .
38420 2a 2a 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41  ** INTEGER PRIMA
38430 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e 20 68 61  RY KEY column ha
38440 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c  s been explicitl
38450 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e  y declared, then
38460 20 74 68 65 20 6f 75 74 70 75 74 20 0a 2a 2a 20   the output .** 
38470 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73  parameters are s
38480 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69  et for the expli
38490 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
384a0 6f 6c 75 6d 6e 2e 20 49 66 20 74 68 65 72 65 20  olumn. If there 
384b0 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69  is no.** explici
384c0 74 6c 79 20 64 65 63 6c 61 72 65 64 20 49 50 4b  tly declared IPK
384d0 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68   column, then th
384e0 65 20 6f 75 74 70 75 74 20 70 61 72 61 6d 65 74  e output paramet
384f0 65 72 73 20 61 72 65 20 73 65 74 20 61 73 20 0a  ers are set as .
38500 2a 2a 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  ** follows:.**.*
38510 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64  * <pre>.**     d
38520 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47  ata type: "INTEG
38530 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61  ER".**     colla
38540 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22  tion sequence: "
38550 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e  BINARY".**     n
38560 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20  ot null: 0.**   
38570 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31    primary key: 1
38580 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63  .**     auto inc
38590 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70  rement: 0.** </p
385a0 72 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  re>.**.** This f
385b0 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64  unction may load
385c0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68   one or more sch
385d0 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61  emas from databa
385e0 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a  se files. If an.
385f0 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  ** error occurs 
38600 64 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63  during this proc
38610 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72  ess, or if the r
38620 65 71 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f  equested table o
38630 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e  r column.** cann
38640 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20  ot be found, an 
38650 53 51 4c 49 54 45 20 65 72 72 6f 72 20 63 6f 64  SQLITE error cod
38660 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  e is returned an
38670 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  d an error messa
38680 67 65 0a 2a 2a 20 6c 65 66 74 20 69 6e 20 74 68  ge.** left in th
38690 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  e database handl
386a0 65 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76  e (to be retriev
386b0 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  ed using sqlite3
386c0 5f 65 72 72 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a  _errmsg())..**.*
386d0 2a 20 54 68 69 73 20 41 50 49 20 69 73 20 6f 6e  * This API is on
386e0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
386f0 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
38700 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
38710 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42  e.** SQLITE_ENAB
38720 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
38730 54 41 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20  TA preprocessor 
38740 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
38750 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
38760 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61  able_column_meta
38770 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20  data(.  sqlite3 
38780 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
38790 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f      /* Connectio
387a0 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  n handle */.  co
387b0 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
387c0 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74  e,        /* Dat
387d0 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55  abase name or NU
387e0 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  LL */.  const ch
387f0 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20  ar *zTableName, 
38800 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d      /* Table nam
38810 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
38820 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20  r *zColumnName, 
38830 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d     /* Column nam
38840 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73  e */.  char cons
38850 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20  t **pzDataType, 
38860 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65     /* OUTPUT: De
38870 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 65  clared data type
38880 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74   */.  char const
38890 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20   **pzCollSeq,   
388a0 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c    /* OUTPUT: Col
388b0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
388c0 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  name */.  int *p
388d0 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20  NotNull,        
388e0 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
388f0 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c   True if NOT NUL
38900 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69  L constraint exi
38910 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50  sts */.  int *pP
38920 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20  rimaryKey,      
38930 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
38940 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70  True if column p
38950 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69  art of PK */.  i
38960 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20  nt *pAutoinc    
38970 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
38980 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f  TPUT: True if co
38990 6c 75 6d 6e 20 69 73