/ Hex Artifact Content
Login

Artifact 5c515eefe7c60008f82fcd1cfbb413d7c426e6c3:


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 38 20 32 30 30 38 2f 30  n,v 1.348 2008/0
05f0: 36 2f 32 31 20 32 30 3a 31 31 3a 31 37 20 6d 69  6/21 20:11:17 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 20 75 73 65 72 20 61 63 74  se to a user act
e890: 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
e8a0: 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
e8b0: 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
e8c0: 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
e8d0: 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
e8e0: 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
e8f0: 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
e900: 2a 0a 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20  *.** It is safe 
e910: 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
e920: 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65  tine from a thre
e930: 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  ad different fro
e940: 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20  m the.** thread 
e950: 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
e960: 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61  y running the da
e970: 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
e980: 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20  .  But it.** is 
e990: 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c  not safe to call
e9a0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
e9b0: 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
e9c0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a  onnection] that.
e9d0: 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  ** is closed or 
e9e0: 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f  might close befo
e9f0: 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  re sqlite3_inter
ea00: 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
ea10: 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 53 51 4c 20  **.** If an SQL 
ea20: 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72  operation is ver
ea30: 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65  y nearly finishe
ea40: 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68  d at the time wh
ea50: 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  en.** sqlite3_in
ea60: 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c  terrupt() is cal
ea70: 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67  led, then it mig
ea80: 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f  ht not have an o
ea90: 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f  pportunity.** to
eaa0: 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20   be interrupted 
eab0: 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e  and might contin
eac0: 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  ue to completion
ead0: 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f  ..**.** An SQL o
eae0: 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73  peration that is
eaf0: 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c   interrupted wil
eb00: 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
eb10: 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20  _INTERRUPT]..** 
eb20: 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74  If the interrupt
eb30: 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  ed SQL operation
eb40: 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55   is an INSERT, U
eb50: 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
eb60: 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69  .** that is insi
eb70: 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  de an explicit t
eb80: 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
eb90: 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
eba0: 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20  saction.** will 
ebb0: 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
ebc0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a  utomatically..**
ebd0: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
ebe0: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
ebf0: 29 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  ) has no effect 
ec00: 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
ec10: 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
ec20: 61 72 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  arted after sqli
ec30: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
ec40: 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  returns..**.** I
ec50: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
ec60: 20 7b 46 31 32 32 37 31 7d 20 54 68 65 20 5b 73   {F12271} The [s
ec70: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
ec80: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
ec90: 6c 6c 20 66 6f 72 63 65 20 61 6c 6c 20 72 75 6e  ll force all run
eca0: 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ning.**         
ecb0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
ecc0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
ecd0: 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
ece0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
ecf0: 20 20 20 20 20 20 20 20 20 74 6f 20 68 61 6c 74           to halt
ed00: 20 61 66 74 65 72 20 70 72 6f 63 65 73 73 69 6e   after processin
ed10: 67 20 61 74 20 6d 6f 73 74 20 6f 6e 65 20 61 64  g at most one ad
ed20: 64 69 74 69 6f 6e 61 6c 20 72 6f 77 20 6f 66 20  ditional row of 
ed30: 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  data..**.** {F12
ed40: 32 37 32 7d 20 41 6e 79 20 53 51 4c 20 73 74 61  272} Any SQL sta
ed50: 74 65 6d 65 6e 74 20 74 68 61 74 20 69 73 20 69  tement that is i
ed60: 6e 74 65 72 72 75 70 74 65 64 20 62 79 20 5b 73  nterrupted by [s
ed70: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
ed80: 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
ed90: 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
eda0: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
edb0: 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e  **.** LIMITATION
edc0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 37 39  S:.**.** {U12279
edd0: 7d 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  } If the databas
ede0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
edf0: 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ses while [sqlit
ee00: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
ee10: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 72  **          is r
ee20: 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20  unning then bad 
ee30: 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65  things will like
ee40: 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f  ly happen..*/.vo
ee50: 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
ee60: 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
ee70: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ee80: 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
ee90: 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
eea0: 73 20 43 6f 6d 70 6c 65 74 65 20 7b 46 31 30 35  s Complete {F105
eeb0: 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  10}.**.** These 
eec0: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
eed0: 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d  ful for command-
eee0: 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
eef0: 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
ef00: 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
ef10: 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
ef20: 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65 20  o form complete 
ef30: 61 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  a SQL statement 
ef40: 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
ef50: 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
ef60: 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
ef70: 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
ef80: 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
ef90: 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20 72  arsing.  These r
efa0: 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
efb0: 72 75 65 20 69 66 20 74 68 65 20 69 6e 70 75 74  rue if the input
efc0: 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
efd0: 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
efe0: 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
eff0: 74 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20  t.  A statement 
f000: 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
f010: 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
f020: 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
f030: 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
f040: 64 20 69 73 20 6e 6f 74 20 61 20 66 72 61 67 6d  d is not a fragm
f050: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45 41  ent of a.** CREA
f060: 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
f070: 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e  ment.  Semicolon
f080: 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
f090: 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
f0a0: 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
f0b0: 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
f0c0: 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
f0d0: 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
f0e0: 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
f0f0: 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
f100: 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
f110: 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
f120: 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
f130: 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
f140: 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
f150: 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  nt terminator..*
f160: 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
f170: 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
f180: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
f190: 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
f1a0: 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
f1b0: 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
f1c0: 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49  ect SQL..**.** I
f1d0: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
f1e0: 20 7b 46 31 30 35 31 31 7d 20 54 68 65 20 73 71   {F10511} The sq
f1f0: 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29  lite3_complete()
f200: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d   and sqlite3_com
f210: 70 6c 65 74 65 31 36 28 29 20 66 75 6e 63 74 69  plete16() functi
f220: 6f 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ons.**          
f230: 72 65 74 75 72 6e 20 74 72 75 65 20 28 6e 6f 6e  return true (non
f240: 2d 7a 65 72 6f 29 20 69 66 20 61 6e 64 20 6f 6e  -zero) if and on
f250: 6c 79 20 69 66 20 74 68 65 20 6c 61 73 74 20 6e  ly if the last n
f260: 6f 6e 2d 77 68 69 74 65 73 70 61 63 65 0a 2a 2a  on-whitespace.**
f270: 20 20 20 20 20 20 20 20 20 20 74 6f 6b 65 6e 20            token 
f280: 69 6e 20 74 68 65 69 72 20 69 6e 70 75 74 20 69  in their input i
f290: 73 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68  s a semicolon th
f2a0: 61 74 20 69 73 20 6e 6f 74 20 69 6e 20 62 65 74  at is not in bet
f2b0: 77 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ween.**         
f2c0: 20 74 68 65 20 42 45 47 49 4e 20 61 6e 64 20 45   the BEGIN and E
f2d0: 4e 44 20 6f 66 20 61 20 43 52 45 41 54 45 20 54  ND of a CREATE T
f2e0: 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
f2f0: 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49  ..**.** LIMITATI
f300: 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 30 35  ONS:.**.** {U105
f310: 31 32 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f  12} The input to
f320: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
f330: 65 28 29 20 6d 75 73 74 20 62 65 20 61 20 7a 65  e() must be a ze
f340: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
f350: 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20            UTF-8 
f360: 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 55  string..**.** {U
f370: 31 30 35 31 33 7d 20 54 68 65 20 69 6e 70 75 74  10513} The input
f380: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   to sqlite3_comp
f390: 6c 65 74 65 31 36 28 29 20 6d 75 73 74 20 62 65  lete16() must be
f3a0: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
f3b0: 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55  ed.**          U
f3c0: 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
f3d0: 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
f3e0: 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
f3f0: 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74  3_complete(const
f400: 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74   char *sql);.int
f410: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
f420: 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a  e16(const void *
f430: 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  sql);../*.** CAP
f440: 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
f450: 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61  A Callback To Ha
f460: 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59  ndle SQLITE_BUSY
f470: 20 45 72 72 6f 72 73 20 7b 46 31 32 33 31 30 7d   Errors {F12310}
f480: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
f490: 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
f4a0: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ack function tha
f4b0: 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
f4c0: 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61  ed whenever.** a
f4d0: 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
f4e0: 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61  e to open a data
f4f0: 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20  base table that 
f500: 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
f510: 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
f520: 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49   locked..**.** I
f530: 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
f540: 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
f550: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
f560: 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
f570: 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20  _BLOCKED].** is 
f580: 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
f590: 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e  tely upon encoun
f5a0: 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e  tering the lock.
f5b0: 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c   If the busy cal
f5c0: 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20  lback.** is not 
f5d0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63  NULL, then the c
f5e0: 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62 65 20  allback will be 
f5f0: 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
f600: 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
f610: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
f620: 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61 6e 64  ment to the hand
f630: 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
f640: 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
f650: 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
f660: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
f670: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
f680: 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 54 68  y_handler().  Th
f690: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
f6a0: 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64  t to.** the hand
f6b0: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
f6c0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
f6d0: 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
f6e0: 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
f6f0: 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
f700: 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65  r this locking e
f710: 76 65 6e 74 2e 20 20 49 66 20 74 68 65 0a 2a 2a  vent.  If the.**
f720: 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72   busy callback r
f730: 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e  eturns 0, then n
f740: 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74  o additional att
f750: 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74  empts are made t
f760: 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20  o.** access the 
f770: 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51  database and [SQ
f780: 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
f790: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
f7a0: 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64  KED] is returned
f7b0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c  ..** If the call
f7c0: 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
f7d0: 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74  -zero, then anot
f7e0: 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69  her attempt.** i
f7f0: 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74  s made to open t
f800: 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20  he database for 
f810: 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20  reading and the 
f820: 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
f830: 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
f840: 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
f850: 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
f860: 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
f870: 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
f880: 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
f890: 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
f8a0: 20 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72   If SQLite deter
f8b0: 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
f8c0: 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  ing the busy.** 
f8d0: 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
f8e0: 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f  sult in a deadlo
f8f0: 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
f900: 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
f910: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
f920: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
f930: 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65  R_BLOCKED] inste
f940: 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74  ad of invoking t
f950: 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
f960: 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73  .** Consider a s
f970: 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e  cenario where on
f980: 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  e process is hol
f990: 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b  ding a read lock
f9a0: 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74   that.** it is t
f9b0: 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65  rying to promote
f9c0: 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c   to a reserved l
f9d0: 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63  ock and.** a sec
f9e0: 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68  ond process is h
f9f0: 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65  olding a reserve
fa00: 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69  d lock that it i
fa10: 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70  s trying.** to p
fa20: 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63  romote to an exc
fa30: 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68  lusive lock.  Th
fa40: 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
fa50: 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a  cannot proceed.*
fa60: 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  * because it is 
fa70: 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73  blocked by the s
fa80: 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65  econd and the se
fa90: 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e  cond process can
faa0: 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62  not.** proceed b
fab0: 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
fac0: 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73  cked by the firs
fad0: 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63  t.  If both proc
fae0: 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20  esses.** invoke 
faf0: 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
fb00: 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20  s, neither will 
fb10: 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73  make any progres
fb20: 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a  s.  Therefore,.*
fb30: 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73  * SQLite returns
fb40: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66   [SQLITE_BUSY] f
fb50: 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  or the first pro
fb60: 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61  cess, hoping tha
fb70: 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69  t this.** will i
fb80: 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20  nduce the first 
fb90: 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61  process to relea
fba0: 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b  se its read lock
fbb0: 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68   and allow.** th
fbc0: 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
fbd0: 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a   to proceed..**.
fbe0: 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62  ** The default b
fbf0: 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
fc00: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
fc10: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72  [SQLITE_BUSY] er
fc20: 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64  ror is converted
fc30: 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   to [SQLITE_IOER
fc40: 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68  R_BLOCKED].** wh
fc50: 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20  en SQLite is in 
fc60: 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20  the middle of a 
fc70: 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f  large transactio
fc80: 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a  n where all the.
fc90: 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20  ** changes will 
fca0: 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65  not fit into the
fcb0: 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65   in-memory cache
fcc0: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a  .  SQLite will.*
fcd0: 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61  * already hold a
fce0: 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f   RESERVED lock o
fcf0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
fd00: 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64  ile, but it need
fd10: 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  s.** to promote 
fd20: 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43  this lock to EXC
fd30: 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69  LUSIVE so that i
fd40: 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68  t can spill cach
fd50: 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20  e.** pages into 
fd60: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
fd70: 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74  e without harm t
fd80: 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20  o concurrent.** 
fd90: 72 65 61 64 65 72 73 2e 20 20 49 66 20 69 74 20  readers.  If it 
fda0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f  is unable to pro
fdb0: 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74  mote the lock, t
fdc0: 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  hen the in-memor
fdd0: 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20  y.** cache will 
fde0: 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e  be left in an in
fdf0: 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65  consistent state
fe00: 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f   and so the erro
fe10: 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f  r.** code is pro
fe20: 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72  moted from the r
fe30: 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e  elatively benign
fe40: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74   [SQLITE_BUSY] t
fe50: 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65  o.** the more se
fe60: 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45  vere [SQLITE_IOE
fe70: 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68  RR_BLOCKED].  Th
fe80: 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72  is error code pr
fe90: 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65  omotion.** force
fea0: 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72  s an automatic r
feb0: 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63  ollback of the c
fec0: 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65  hanges.  See the
fed0: 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76  .** <a href="/cv
fee0: 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72  strac/wiki?p=Cor
fef0: 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
ff00: 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43  BusyError">.** C
ff10: 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
ff20: 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20  ngBusyError</a> 
ff30: 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20  wiki page for a 
ff40: 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68  discussion of wh
ff50: 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70  y.** this is imp
ff60: 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  ortant..**.** Th
ff70: 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
ff80: 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
ff90: 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f  ndler defined fo
ffa0: 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  r each.** [datab
ffb0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
ffc0: 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20    Setting a new 
ffd0: 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65  busy handler cle
ffe0: 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69  ars any.** previ
fff0: 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65  ously set handle
10000 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 63 61  r.  Note that ca
10010 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  lling [sqlite3_b
10020 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a  usy_timeout()].*
10030 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20  * will also set 
10040 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73  or clear the bus
10050 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
10060 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
10070 2a 2a 20 7b 46 31 32 33 31 31 7d 20 54 68 65 20  ** {F12311} The 
10080 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
10090 6e 64 6c 65 72 28 29 5d 20 66 75 6e 63 74 69 6f  ndler()] functio
100a0 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 62  n replaces the b
100b0 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 20  usy handler.**  
100c0 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b          callback
100d0 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
100e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 64 65 6e   connection iden
100f0 74 69 66 69 65 64 20 62 79 20 74 68 65 20 31 73  tified by the 1s
10100 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  t.**          pa
10110 72 61 6d 65 74 65 72 20 77 69 74 68 20 61 20 6e  rameter with a n
10120 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
10130 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
10140 65 20 32 6e 64 20 61 6e 64 20 33 72 64 0a 2a 2a  e 2nd and 3rd.**
10150 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65            parame
10160 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ters..**.** {F12
10170 33 31 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74  312} The default
10180 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
10190 72 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  r new database c
101a0 6f 6e 6e 65 63 74 69 6f 6e 73 20 69 73 20 4e 55  onnections is NU
101b0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31  LL..**.** {F1231
101c0 34 7d 20 57 68 65 6e 20 74 77 6f 20 6f 72 20 6d  4} When two or m
101d0 6f 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ore database con
101e0 6e 65 63 74 69 6f 6e 20 73 68 61 72 65 20 61 0a  nection share a.
101f0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
10200 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
10210 65 64 5f 63 61 63 68 65 20 7c 20 63 6f 6d 6d 6f  ed_cache | commo
10220 6e 20 63 61 63 68 65 5d 2c 0a 2a 2a 20 20 20 20  n cache],.**    
10230 20 20 20 20 20 20 74 68 65 20 62 75 73 79 20 68        the busy h
10240 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 64  andler for the d
10250 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10260 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  on currently usi
10270 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ng.**          t
10280 68 65 20 63 61 63 68 65 20 69 73 20 69 6e 76 6f  he cache is invo
10290 6b 65 64 20 77 68 65 6e 20 74 68 65 20 63 61 63  ked when the cac
102a0 68 65 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20  he encounters a 
102b0 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  lock..**.** {F12
102c0 33 31 36 7d 20 49 66 20 61 20 62 75 73 79 20 68  316} If a busy h
102d0 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
102e0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
102f0 65 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e  en the SQLite in
10300 74 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20  terface.**      
10310 20 20 20 20 74 68 61 74 20 70 72 6f 76 6f 6b 65      that provoke
10320 64 20 74 68 65 20 6c 6f 63 6b 69 6e 67 20 65 76  d the locking ev
10330 65 6e 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ent will return 
10340 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a  [SQLITE_BUSY]..*
10350 2a 0a 2a 2a 20 7b 46 31 32 33 31 38 7d 20 53 51  *.** {F12318} SQ
10360 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
10370 73 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  s the busy handl
10380 65 72 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  er with two argu
10390 6d 65 6e 74 73 20 77 68 69 63 68 0a 2a 2a 20 20  ments which.**  
103a0 20 20 20 20 20 20 20 20 61 72 65 20 61 20 63 6f          are a co
103b0 70 79 20 6f 66 20 74 68 65 20 70 6f 69 6e 74 65  py of the pointe
103c0 72 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68  r supplied by th
103d0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
103e0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
103f0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
10400 64 6c 65 72 28 29 5d 20 61 6e 64 20 61 20 63 6f  dler()] and a co
10410 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  unt of the numbe
10420 72 20 6f 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20  r of prior.**   
10430 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f         invocatio
10440 6e 73 20 6f 66 20 74 68 65 20 62 75 73 79 20 68  ns of the busy h
10450 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 73  andler for the s
10460 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  ame locking even
10470 74 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54  t..**.** LIMITAT
10480 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32  IONS:.**.** {U12
10490 33 31 39 7d 20 41 20 62 75 73 79 20 68 61 6e 64  319} A busy hand
104a0 6c 65 72 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ler should not c
104b0 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
104c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
104d0 20 20 20 20 20 20 20 20 20 6f 72 20 5b 70 72 65           or [pre
104e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
104f0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
10500 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
10510 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
10520 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
10530 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
10540 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
10550 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10560 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
10570 65 6f 75 74 20 7b 46 31 32 33 34 30 7d 0a 2a 2a  eout {F12340}.**
10580 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
10590 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
105a0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
105b0 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68  busy handler] th
105c0 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72  at sleeps.** for
105d0 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f   a specified amo
105e0 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e  unt of time when
105f0 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b   a table is lock
10600 65 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72  ed.  The handler
10610 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
10620 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
10630 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
10640 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
10650 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
10660 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
10670 7b 46 31 32 33 34 33 7d 20 41 66 74 65 72 20 22  {F12343} After "
10680 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
10690 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a   of sleeping,.**
106a0 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74   the handler ret
106b0 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75  urns 0 which cau
106c0 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ses [sqlite3_ste
106d0 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a  p()] to return.*
106e0 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  * [SQLITE_BUSY] 
106f0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
10700 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a  _BLOCKED]..**.**
10710 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f   Calling this ro
10720 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
10730 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
10740 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
10750 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
10760 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
10770 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61  ..**.** There ca
10780 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
10790 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
107a0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
107b0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
107c0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e  nnection] any an
107d0 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
107e0 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
107f0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
10800 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
10810 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
10820 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
10830 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
10840 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
10850 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
10860 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a  ler is cleared..
10870 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
10880 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 31 7d  :.**.** {F12341}
10890 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75   The [sqlite3_bu
108a0 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 66 75  sy_timeout()] fu
108b0 6e 63 74 69 6f 6e 20 6f 76 65 72 72 69 64 65 73  nction overrides
108c0 20 61 6e 79 20 70 72 69 6f 72 0a 2a 2a 20 20 20   any prior.**   
108d0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
108e0 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
108f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  or [sqlite3_busy
10900 5f 68 61 6e 64 6c 65 72 28 29 5d 20 73 65 74 74  _handler()] sett
10910 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
10920 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
10930 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
10940 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 33 7d 20  .**.** {F12343} 
10950 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
10960 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
10970 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
10980 20 69 73 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a   is less than.**
10990 20 20 20 20 20 20 20 20 20 20 6f 72 20 65 71 75            or equ
109a0 61 6c 20 74 6f 20 7a 65 72 6f 2c 20 74 68 65 6e  al to zero, then
109b0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
109c0 72 20 69 73 20 63 6c 65 61 72 65 64 20 73 6f 20  r is cleared so 
109d0 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  that.**         
109e0 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
109f0 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 73 20 69  locking events i
10a00 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74 75 72  mmediately retur
10a10 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  n [SQLITE_BUSY].
10a20 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 34 34 7d 20  .**.** {F12344} 
10a30 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
10a40 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
10a50 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
10a60 20 69 73 20 61 20 70 6f 73 69 74 69 76 65 0a 2a   is a positive.*
10a70 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65  *          numbe
10a80 72 20 4e 2c 20 74 68 65 6e 20 61 20 62 75 73 79  r N, then a busy
10a90 20 68 61 6e 64 6c 65 72 20 69 73 20 73 65 74 20   handler is set 
10aa0 74 68 61 74 20 72 65 70 65 61 74 65 64 6c 79 20  that repeatedly 
10ab0 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20  calls.**        
10ac0 20 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d    the xSleep() m
10ad0 65 74 68 6f 64 20 69 6e 20 74 68 65 20 56 46 53  ethod in the VFS
10ae0 20 69 6e 74 65 72 66 61 63 65 20 75 6e 74 69 6c   interface until
10af0 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 20   either the.**  
10b00 20 20 20 20 20 20 20 20 6c 6f 63 6b 20 63 6c 65          lock cle
10b10 61 72 73 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ars or until the
10b20 20 63 75 6d 75 6c 61 74 69 76 65 20 73 6c 65 65   cumulative slee
10b30 70 20 74 69 6d 65 20 72 65 70 6f 72 74 65 64 20  p time reported 
10b40 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
10b50 20 62 79 20 78 53 6c 65 65 70 28 29 20 65 78 63   by xSleep() exc
10b60 65 65 64 73 20 4e 20 6d 69 6c 6c 69 73 65 63 6f  eeds N milliseco
10b70 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  nds..*/.int sqli
10b80 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
10b90 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
10ba0 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
10bb0 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
10bc0 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
10bd0 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 20 7b 46  nning Queries {F
10be0 31 32 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 44 65 66  12370}.**.** Def
10bf0 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65  inition: A <b>re
10c00 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69  sult table</b> i
10c10 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74  s memory data st
10c20 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20  ructure created 
10c30 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  by the.** [sqlit
10c40 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
10c50 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65  interface.  A re
10c60 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72  sult table recor
10c70 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  ds the.** comple
10c80 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  te query results
10c90 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72   from one or mor
10ca0 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a  e queries..**.**
10cb0 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65   The table conce
10cc0 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75  ptually has a nu
10cd0 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64  mber of rows and
10ce0 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a   columns.  But.*
10cf0 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20  * these numbers 
10d00 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20  are not part of 
10d10 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
10d20 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a   itself.  These.
10d30 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f  ** numbers are o
10d40 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65  btained separate
10d50 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68  ly.  Let N be th
10d60 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
10d70 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65  .** and M be the
10d80 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
10d90 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  ns..**.** A resu
10da0 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61  lt table is an a
10db0 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
10dc0 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
10dd0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
10de0 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  s..** There are 
10df0 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73  (N+1)*M elements
10e00 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20   in the array.  
10e10 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e  The first M poin
10e20 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f  ters point.** to
10e30 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
10e40 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63   strings that  c
10e50 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  ontain the names
10e60 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e   of the columns.
10e70 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
10e80 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f  g entries all po
10e90 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73  int to query res
10ea0 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75  ults.  NULL valu
10eb0 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20  es result.** in 
10ec0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20  NULL pointers.  
10ed0 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73  All other values
10ee0 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54   are in their UT
10ef0 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
10f00 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65  ted.** string re
10f10 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20  presentation as 
10f20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
10f30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
10f40 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  ()]..**.** A res
10f50 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20  ult table might 
10f60 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f  consist of one o
10f70 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c  r more memory al
10f80 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74  locations..** It
10f90 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
10fa0 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61  pass a result ta
10fb0 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20  ble directly to 
10fc0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
10fd0 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  ..** A result ta
10fe0 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65  ble should be de
10ff0 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20  allocated using 
11000 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
11010 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73  ble()]..**.** As
11020 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
11030 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
11040 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
11050 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
11060 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
11070 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
11080 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
11090 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
110a0 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   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 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
110d0 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
110e0 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
110f0 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
11100 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
11110 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
11120 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
11130 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
11140 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
11150 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
11160 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
11170 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
11180 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
11190 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
111a0 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
111b0 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
111c0 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
111d0 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
111e0 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
111f0 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
11200 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
11210 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
11220 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
11230 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
11240 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
11250 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
11260 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
11270 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
11280 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
11290 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
112a0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
112b0 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
112c0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
112d0 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
112e0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
112f0 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
11300 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
11310 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
11320 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
11330 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
11340 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
11350 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
11360 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
11370 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
11380 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
11390 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
113a0 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
113b0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
113c0 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
113d0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
113e0 20 49 74 20 72 65 74 75 72 6e 73 20 61 20 72 65   It returns a re
113f0 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
11400 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
11410 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
11420 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
11430 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67  fter the calling
11440 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69   function has fi
11450 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65  nished using the
11460 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75   result, it shou
11470 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 70  ld.** pass the p
11480 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 72 65  ointer to the re
11490 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 73 71  sult table to sq
114a0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
114b0 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
114c0 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
114d0 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
114e0 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
114f0 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
11500 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
11510 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
11520 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
11530 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
11540 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
11550 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
11560 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
11570 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
11580 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
11590 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
115a0 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
115b0 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
115c0 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
115d0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
115e0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
115f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
11600 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
11610 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
11620 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
11630 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
11640 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
11650 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
11660 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
11670 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
11680 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
11690 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
116a0 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
116b0 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
116c0 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
116d0 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
116e0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
116f0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
11700 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
11710 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
11720 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
11730 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
11740 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
11750 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
11760 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
11770 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  code()] or [sqli
11780 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
11790 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
117a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 31 7d 20  .**.** {F12371} 
117b0 49 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 67 65  If a [sqlite3_ge
117c0 74 5f 74 61 62 6c 65 28 29 5d 20 66 61 69 6c 73  t_table()] fails
117d0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
117e0 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  tion, then.**   
117f0 20 20 20 20 20 20 20 69 74 20 66 72 65 65 73 20         it frees 
11800 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
11810 20 75 6e 64 65 72 20 63 6f 6e 73 74 72 75 63 74   under construct
11820 69 6f 6e 2c 20 61 62 6f 72 74 73 20 74 68 65 0a  ion, aborts the.
11830 2a 2a 20 20 20 20 20 20 20 20 20 20 71 75 65 72  **          quer
11840 79 20 69 6e 20 70 72 6f 63 65 73 73 2c 20 73 6b  y in process, sk
11850 69 70 73 20 61 6e 79 20 73 75 62 73 65 71 75 65  ips any subseque
11860 6e 74 20 71 75 65 72 69 65 73 2c 20 73 65 74 73  nt queries, sets
11870 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
11880 20 2a 72 65 73 75 6c 74 70 20 6f 75 74 70 75 74   *resultp output
11890 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c   pointer to NULL
118a0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 5b 53 51   and returns [SQ
118b0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
118c0 2a 2a 20 7b 46 31 32 33 37 33 7d 20 49 66 20 74  ** {F12373} If t
118d0 68 65 20 6e 63 6f 6c 75 6d 6e 20 70 61 72 61 6d  he ncolumn param
118e0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
118f0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 73  _get_table()] is
11900 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20   not NULL.**    
11910 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69        then [sqli
11920 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
11930 20 77 72 69 74 65 73 20 74 68 65 20 6e 75 6d 62   writes the numb
11940 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
11950 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
11960 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
11970 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a 6e  he query into *n
11980 63 6f 6c 75 6d 6e 20 69 66 20 74 68 65 20 71 75  column if the qu
11990 65 72 79 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ery is.**       
119a0 20 20 20 73 75 63 63 65 73 73 66 75 6c 20 28 69     successful (i
119b0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72  f the function r
119c0 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b  eturns SQLITE_OK
119d0 29 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 34  )..**.** {F12374
119e0 7d 20 49 66 20 74 68 65 20 6e 72 6f 77 20 70 61  } If the nrow pa
119f0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
11a00 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
11a10 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20   is not NULL.** 
11a20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73           then [s
11a30 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
11a40 28 29 5d 20 77 72 69 74 65 73 20 74 68 65 20 6e  ()] writes the n
11a50 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e  umber of rows in
11a60 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
11a70 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
11a80 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a 6e  he query into *n
11a90 72 6f 77 20 69 66 20 74 68 65 20 71 75 65 72 79  row if the query
11aa0 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
11ab0 73 75 63 63 65 73 73 66 75 6c 20 28 69 66 20 74  successful (if t
11ac0 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
11ad0 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 29 2e 0a  rns SQLITE_OK)..
11ae0 2a 2a 0a 2a 2a 20 7b 46 31 32 33 37 36 7d 20 54  **.** {F12376} T
11af0 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  he [sqlite3_get_
11b00 74 61 62 6c 65 28 29 5d 20 66 75 6e 63 74 69 6f  table()] functio
11b10 6e 20 73 65 74 73 20 69 74 73 20 2a 6e 63 6f 6c  n sets its *ncol
11b20 75 6d 6e 20 76 61 6c 75 65 20 74 6f 20 74 68 65  umn value to the
11b30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
11b40 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
11b50 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
11b60 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 6e   of the query in
11b70 20 74 68 65 20 73 71 6c 0a 2a 2a 20 20 20 20 20   the sql.**     
11b80 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2c 20       parameter, 
11b90 6f 72 20 74 6f 20 7a 65 72 6f 20 69 66 20 74 68  or to zero if th
11ba0 65 20 71 75 65 72 79 20 69 6e 20 73 71 6c 20 68  e query in sql h
11bb0 61 73 20 61 6e 20 65 6d 70 74 79 20 72 65 73 75  as an empty resu
11bc0 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73  lt set..*/.int s
11bd0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
11be0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
11bf0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
11c00 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
11c10 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
11c20 71 6c 2c 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  ql,      /* SQL 
11c30 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
11c40 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 52 65  */.  char ***pRe
11c50 73 75 6c 74 2c 20 20 20 20 20 20 2f 2a 20 52 65  sult,      /* Re
11c60 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
11c70 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 72 6f  ry */.  int *nro
11c80 77 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  w,            /*
11c90 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
11ca0 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
11cb0 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 6e 63  ere */.  int *nc
11cc0 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 20 2f  olumn,         /
11cd0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
11ce0 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
11cf0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
11d00 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20  r **errmsg      
11d10 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
11d20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
11d30 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
11d40 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20  free_table(char 
11d50 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a  **result);../*.*
11d60 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d  * CAPI3REF: Form
11d70 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69  atted String Pri
11d80 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20  nting Functions 
11d90 7b 46 31 37 34 30 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F17400}.**.** T
11da0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
11db0 65 20 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20  e workalikes of 
11dc0 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
11dd0 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
11de0 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
11df0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
11e00 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
11e10 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
11e20 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
11e30 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
11e40 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
11e50 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
11e60 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
11e70 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
11e80 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
11e90 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
11ea0 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
11eb0 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
11ec0 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
11ed0 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 20 42  te3_free()].   B
11ee0 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
11ef0 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
11f00 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
11f10 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
11f20 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
11f30 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
11f40 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
11f50 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
11f60 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65  .**.** In sqlite
11f70 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
11f80 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
11f90 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
11fa0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
11fb0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
11fc0 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
11fd0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
11fe0 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
11ff0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
12000 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
12010 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
12020 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
12030 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
12040 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
12050 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
12060 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
12070 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
12080 70 72 69 6e 74 66 28 29 2e 20 20 54 68 69 73 20  printf().  This 
12090 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
120a0 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
120b0 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
120c0 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
120d0 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
120e0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
120f0 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73  Note also that s
12100 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
12110 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70  ).** returns a p
12120 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75  ointer to its bu
12130 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  ffer instead of 
12140 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
12150 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75   characters actu
12160 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74  ally written int
12170 6f 20 74 68 65 20 62 75 66 66 65 72 2e 20 20 57  o the buffer.  W
12180 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20  e admit that.** 
12190 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
121a0 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e  aracters written
121b0 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65   would be a more
121c0 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a   useful return.*
121d0 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63  * value but we c
121e0 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
121f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
12200 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
12210 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74  ntf().** now wit
12220 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f  hout breaking co
12230 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
12240 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  ** As long as th
12250 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
12260 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
12270 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
12280 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
12290 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
122a0 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
122b0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
122c0 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61   The first.** pa
122d0 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
122e0 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
122f0 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
12300 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
12310 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
12320 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
12330 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
12340 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
12350 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
12360 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
12370 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
12380 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
12390 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
123a0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
123b0 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
123c0 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
123d0 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
123e0 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
123f0 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
12400 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29  e usual printf()
12410 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
12420 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
12430 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
12440 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
12450 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70  %Q", and "%z" op
12460 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
12470 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
12480 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
12490 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
124a0 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65  a null-terminate
124b0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
124c0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
124d0 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
124e0 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
124f0 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
12500 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
12510 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
12520 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
12530 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  .  By doubling e
12540 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
12550 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
12560 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
12570 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
12580 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
12590 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
125a0 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
125b0 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73  le, assume the s
125c0 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a  tring variable z
125d0 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65  Text contains te
125e0 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  xt as follows:.*
125f0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
12600 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
12610 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61  *zText = "It's a
12620 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a   happy day!";.**
12630 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
12640 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63  ote>.**.** One c
12650 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74  an use this text
12660 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
12670 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ment as follows:
12680 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
12690 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
126a0 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
126b0 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
126c0 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
126d0 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78  UES('%q')", zTex
126e0 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
126f0 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
12700 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
12710 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
12720 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
12730 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65  kquote>.**.** Be
12740 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72  cause the %q for
12750 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73  mat string is us
12760 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61  ed, the '\'' cha
12770 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a  racter in zText.
12780 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e  ** is escaped an
12790 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61  d the SQL genera
127a0 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ted is as follow
127b0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
127c0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
127d0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
127e0 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20  1 VALUES('It''s 
127f0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a  a happy day!').*
12800 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
12810 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
12820 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61   is correct.  Ha
12830 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73  d we used %s ins
12840 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20  tead of %q, the 
12850 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a  generated SQL.**
12860 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b   would have look
12870 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ed like this:.**
12880 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
12890 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
128a0 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
128b0 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70  UES('It's a happ
128c0 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70  y day!');.** </p
128d0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
128e0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f  .**.** This seco
128f0 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e  nd example is an
12900 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f   SQL syntax erro
12910 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c  r.  As a general
12920 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64   rule you should
12930 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25  .** always use %
12940 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20  q instead of %s 
12950 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74  when inserting t
12960 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e  ext into a strin
12970 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  g literal..**.**
12980 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77   The %Q option w
12990 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
129a0 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
129b0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
129c0 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
129d0 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
129e0 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
129f0 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
12a00 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
12a10 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
12a20 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
12a30 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
12a40 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
12a50 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
12a60 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 20 69  single quotes) i
12a70 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 25  n place of the %
12a80 51 20 6f 70 74 69 6f 6e 2e 20 7b 45 4e 44 7d 20  Q option. {END} 
12a90 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
12aa0 2c 0a 2a 2a 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ,.** one could s
12ab0 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
12ac0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
12ad0 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
12ae0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
12af0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
12b00 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
12b10 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
12b20 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
12b30 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
12b40 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
12b50 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
12b60 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
12b70 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
12b80 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
12b90 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
12ba0 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
12bb0 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
12bc0 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
12bd0 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
12be0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
12bf0 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
12c00 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65  g option works e
12c10 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22  xactly like "%s"
12c20 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
12c30 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
12c40 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
12c50 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
12c60 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
12c70 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
12c80 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
12c90 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
12ca0 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a   string. {END}.*
12cb0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
12cc0 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 33 7d 20  .**.** {F17403} 
12cd0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 70   The [sqlite3_mp
12ce0 72 69 6e 74 66 28 29 5d 20 61 6e 64 20 5b 73 71  rintf()] and [sq
12cf0 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
12d00 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ] interfaces.** 
12d10 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
12d20 20 65 69 74 68 65 72 20 70 6f 69 6e 74 65 72 73   either pointers
12d30 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
12d40 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
12d50 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 20 20 20  s held in.**    
12d60 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 6f 62         memory ob
12d70 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
12d80 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
12d90 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  r NULL pointers 
12da0 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  if.**           
12db0 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
12dc0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 61 69  e3_malloc()] fai
12dd0 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30  ls..**.** {F1740
12de0 36 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  6}  The [sqlite3
12df0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74  _snprintf()] int
12e00 65 72 66 61 63 65 20 77 72 69 74 65 73 20 61 20  erface writes a 
12e10 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
12e20 2a 2a 20 20 20 20 20 20 20 20 20 20 20 55 54 46  **           UTF
12e30 2d 38 20 73 74 72 69 6e 67 20 69 6e 74 6f 20 74  -8 string into t
12e40 68 65 20 62 75 66 66 65 72 20 70 6f 69 6e 74 65  he buffer pointe
12e50 64 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  d to by the seco
12e60 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
12e70 20 20 20 20 20 20 20 20 20 20 70 72 6f 76 69 64            provid
12e80 65 64 20 74 68 61 74 20 74 68 65 20 66 69 72 73  ed that the firs
12e90 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 67  t parameter is g
12ea0 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
12eb0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 37 7d  ..**.** {F17407}
12ec0 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73    The [sqlite3_s
12ed0 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72  nprintf()] inter
12ee0 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 77 72  face does not wr
12ef0 69 74 65 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a 20  ite slots of.** 
12f00 20 20 20 20 20 20 20 20 20 20 69 74 73 20 6f 75            its ou
12f10 74 70 75 74 20 62 75 66 66 65 72 20 28 74 68 65  tput buffer (the
12f20 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
12f30 72 29 20 6f 75 74 73 69 64 65 20 74 68 65 20 72  r) outside the r
12f40 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  ange.**         
12f50 20 20 6f 66 20 30 20 74 68 72 6f 75 67 68 20 4e    of 0 through N
12f60 2d 31 20 28 77 68 65 72 65 20 4e 20 69 73 20 74  -1 (where N is t
12f70 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
12f80 65 72 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  er).**          
12f90 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
12fa0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
12fb0 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20   string.**      
12fc0 20 20 20 20 20 72 65 71 75 65 73 74 65 64 20 62       requested b
12fd0 79 20 74 68 65 20 66 6f 72 6d 61 74 20 73 70 65  y the format spe
12fe0 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2f 0a 63  cification..*/.c
12ff0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72  har *sqlite3_mpr
13000 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
13010 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c  ,...);.char *sql
13020 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f  ite3_vmprintf(co
13030 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
13040 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  st);.char *sqlit
13050 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  e3_snprintf(int,
13060 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
13070 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, ...);../*.** 
13080 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
13090 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
130a0 79 73 74 65 6d 20 7b 46 31 37 33 30 30 7d 0a 2a  ystem {F17300}.*
130b0 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
130c0 63 6f 72 65 20 20 75 73 65 73 20 74 68 65 73 65  core  uses these
130d0 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20   three routines 
130e0 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f  for all of its o
130f0 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d  wn.** internal m
13100 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13110 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69   needs. "Core" i
13120 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  n the previous s
13130 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20  entence.** does 
13140 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72  not include oper
13150 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
13160 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d  cific VFS implem
13170 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a  entation.  The.*
13180 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73  * Windows VFS us
13190 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63  es native malloc
131a0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f  () and free() fo
131b0 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e  r some operation
131c0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
131d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f  ite3_malloc() ro
131e0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
131f0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f  pointer to a blo
13200 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  ck.** of memory 
13210 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
13220 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72   in length, wher
13230 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d  e N is the param
13240 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71 6c 69  eter..** If sqli
13250 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
13260 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
13270 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
13280 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
13290 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
132a0 69 6e 74 65 72 2e 20 20 49 66 20 74 68 65 20 70  inter.  If the p
132b0 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a  arameter N to.**
132c0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
132d0 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67  ) is zero or neg
132e0 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74  ative then sqlit
132f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75  e3_malloc() retu
13300 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  rns.** a NULL po
13310 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  inter..**.** Cal
13320 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
13330 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
13340 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
13350 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
13360 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
13370 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
13380 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
13390 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
133a0 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
133b0 65 75 73 65 64 2e 20 20 54 68 65 20 73 71 6c 69  eused.  The sqli
133c0 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
133d0 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
133e0 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
133f0 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
13400 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
13410 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
13420 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
13430 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
13440 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
13450 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
13460 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
13470 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
13480 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
13490 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
134a0 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
134b0 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
134c0 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
134d0 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
134e0 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
134f0 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
13500 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
13510 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
13520 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
13530 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
13540 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
13550 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
13560 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
13570 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
13580 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
13590 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
135a0 74 65 33 5f 66 72 65 65 28 29 2e 0a 2a 2a 0a 2a  te3_free()..**.*
135b0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
135c0 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63  alloc() interfac
135d0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
135e0 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
135f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13600 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  n to be at least
13610 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20   N bytes, where 
13620 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f  N is the.** seco
13630 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
13640 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
13650 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a  tion to be resiz
13660 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  ed is the first.
13670 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  ** parameter.  I
13680 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
13690 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
136a0 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
136b0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
136c0 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
136d0 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
136e0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
136f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77  ite3_malloc(N) w
13700 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
13710 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
13720 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
13730 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73  c()..** If the s
13740 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
13750 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
13760 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  oc() is zero or.
13770 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
13780 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
13790 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
137a0 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
137b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20  sqlite3_free(P) 
137c0 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66  where P is the f
137d0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
137e0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
137f0 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  c()..** sqlite3_
13800 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
13810 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
13820 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13830 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
13840 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
13850 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66  e or NULL if suf
13860 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
13870 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
13880 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20 73 69  * If M is the si
13890 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
138a0 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
138b0 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
138c0 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
138d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
138e0 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
138f0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
13900 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
13910 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
13920 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  c() and the prio
13930 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
13940 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c  freed..** If sql
13950 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
13960 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
13970 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  n the prior allo
13980 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74  cation.** is not
13990 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68   freed..**.** Th
139a0 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
139b0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
139c0 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65  loc() and sqlite
139d0 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
139e0 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
139f0 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
13a00 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8 byte boundary.
13a10 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
13a20 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65   default impleme
13a30 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 6d  ntation of the m
13a40 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13a50 20 73 75 62 73 79 73 74 65 6d 20 75 73 65 73 0a   subsystem uses.
13a60 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c  ** the malloc(),
13a70 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66   realloc() and f
13a80 72 65 65 28 29 20 70 72 6f 76 69 64 65 64 20 62  ree() provided b
13a90 79 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  y the standard C
13aa0 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b 46 31   library..** {F1
13ab0 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20 69  7382} However, i
13ac0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
13ad0 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
13ae0 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53   SQLITE_MEMORY_S
13af0 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43  IZE=<i>NNN</i> C
13b00 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
13b10 63 72 6f 20 28 77 68 65 72 65 20 3c 69 3e 4e 4e  cro (where <i>NN
13b20 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e 20 69  N</i>.** is an i
13b30 6e 74 65 67 65 72 29 2c 20 74 68 65 6e 20 53 51  nteger), then SQ
13b40 4c 69 74 65 20 63 72 65 61 74 65 20 61 20 73 74  Lite create a st
13b50 61 74 69 63 20 61 72 72 61 79 20 6f 66 20 61 74  atic array of at
13b60 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e   least.** <i>NNN
13b70 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73 69  </i> bytes in si
13b80 7a 65 20 61 6e 64 20 75 73 65 73 20 74 68 61 74  ze and uses that
13b90 20 61 72 72 61 79 20 66 6f 72 20 61 6c 6c 20 6f   array for all o
13ba0 66 20 69 74 73 20 64 79 6e 61 6d 69 63 0a 2a 2a  f its dynamic.**
13bb0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13bc0 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20  on needs. {END} 
13bd0 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f   Additional memo
13be0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74  ry allocator opt
13bf0 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61  ions.** may be a
13c00 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
13c10 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49  eleases..**.** I
13c20 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
13c30 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31   3.5.0 and 3.5.1
13c40 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c  , it was possibl
13c50 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74  e to define.** t
13c60 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  he SQLITE_OMIT_M
13c70 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
13c80 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75   which would cau
13c90 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  se the built-in.
13ca0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
13cb0 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  n of these routi
13cc0 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65  nes to be omitte
13cd0 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c  d.  That capabil
13ce0 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e  ity.** is no lon
13cf0 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f  ger provided.  O
13d00 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  nly built-in mem
13d10 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63  ory allocators c
13d20 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a  an be used..**.*
13d30 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53  * The Windows OS
13d40 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
13d50 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79   calls.** the sy
13d60 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  stem malloc() an
13d70 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c  d free() directl
13d80 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e  y when convertin
13d90 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62  g.** filenames b
13da0 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38  etween the UTF-8
13db0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62   encoding used b
13dc0 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
13dd0 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d  whatever filenam
13de0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  e encoding is us
13df0 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63  ed by the partic
13e00 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20  ular Windows.** 
13e10 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d  installation.  M
13e20 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13e30 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65   errors are dete
13e40 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65  cted, but.** the
13e50 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62  y are reported b
13e60 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
13e70 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
13e80 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
13e90 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
13ea0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
13eb0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
13ec0 2a 20 7b 46 31 37 33 30 33 7d 20 20 54 68 65 20  * {F17303}  The 
13ed0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13ee0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
13ef0 74 75 72 6e 73 20 65 69 74 68 65 72 20 61 20 70  turns either a p
13f00 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20  ointer to.**    
13f10 20 20 20 20 20 20 20 61 20 6e 65 77 6c 79 20 63         a newly c
13f20 68 65 63 6b 65 64 2d 6f 75 74 20 62 6c 6f 63 6b  hecked-out block
13f30 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
13f40 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ytes of memory.*
13f50 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61 74  *           that
13f60 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   is 8-byte align
13f70 65 64 2c 20 6f 72 20 69 74 20 72 65 74 75 72 6e  ed, or it return
13f80 73 20 4e 55 4c 4c 20 69 66 20 69 74 20 69 73 20  s NULL if it is 
13f90 75 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20  unable.**       
13fa0 20 20 20 20 74 6f 20 66 75 6c 66 69 6c 6c 20 74      to fulfill t
13fb0 68 65 20 72 65 71 75 65 73 74 2e 0a 2a 2a 0a 2a  he request..**.*
13fc0 2a 20 7b 46 31 37 33 30 34 7d 20 20 54 68 65 20  * {F17304}  The 
13fd0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13fe0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
13ff0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
14000 6e 74 65 72 20 69 66 0a 2a 2a 20 20 20 20 20 20  nter if.**      
14010 20 20 20 20 20 4e 20 69 73 20 6c 65 73 73 20 74       N is less t
14020 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
14030 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  zero..**.** {F17
14040 33 30 35 7d 20 20 54 68 65 20 5b 73 71 6c 69 74  305}  The [sqlit
14050 65 33 5f 66 72 65 65 28 50 29 5d 20 69 6e 74 65  e3_free(P)] inte
14060 72 66 61 63 65 20 72 65 6c 65 61 73 65 73 20 6d  rface releases m
14070 65 6d 6f 72 79 20 70 72 65 76 69 6f 75 73 6c 79  emory previously
14080 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
14090 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
140a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
140b0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
140c0 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  oc()],.**       
140d0 20 20 20 20 6d 61 6b 69 6e 67 20 69 74 20 61 76      making it av
140e0 61 69 6c 61 62 6c 65 20 66 6f 72 20 72 65 75 73  ailable for reus
140f0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 30 36  e..**.** {F17306
14100 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71  }  A call to [sq
14110 6c 69 74 65 33 5f 66 72 65 65 28 4e 55 4c 4c 29  lite3_free(NULL)
14120 5d 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  ] is a harmless 
14130 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  no-op..**.** {F1
14140 37 33 31 30 7d 20 20 41 20 63 61 6c 6c 20 74 6f  7310}  A call to
14150 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
14160 63 28 30 2c 4e 29 5d 20 69 73 20 65 71 75 69 76  c(0,N)] is equiv
14170 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a  alent to a call.
14180 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20  **           to 
14190 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
141a0 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  N)]..**.** {F173
141b0 31 32 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b  12}  A call to [
141c0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
141d0 50 2c 30 29 5d 20 69 73 20 65 71 75 69 76 61 6c  P,0)] is equival
141e0 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a  ent to a call.**
141f0 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73             to [s
14200 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d 2e  qlite3_free(P)].
14210 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 35 7d 20  .**.** {F17315} 
14220 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
14230 20 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d   uses [sqlite3_m
14240 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
14250 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  e3_realloc()],.*
14260 2a 20 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  *           and 
14270 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
14280 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
14290 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
142a0 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  n and.**        
142b0 20 20 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 20     deallocation 
142c0 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  needs..**.** {F1
142d0 37 33 31 38 7d 20 20 54 68 65 20 5b 73 71 6c 69  7318}  The [sqli
142e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29  te3_realloc(P,N)
142f0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
14300 72 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f 69  rns either a poi
14310 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  nter.**         
14320 20 20 74 6f 20 61 20 62 6c 6f 63 6b 20 6f 66 20    to a block of 
14330 63 68 65 63 6b 65 64 2d 6f 75 74 20 6d 65 6d 6f  checked-out memo
14340 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ry of at least N
14350 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 0a 2a   bytes in size.*
14360 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61 74  *           that
14370 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   is 8-byte align
14380 65 64 2c 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  ed, or a NULL po
14390 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  inter..**.** {F1
143a0 37 33 32 31 7d 20 20 57 68 65 6e 20 5b 73 71 6c  7321}  When [sql
143b0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e  ite3_realloc(P,N
143c0 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  )] returns a non
143d0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69  -NULL pointer, i
143e0 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20  t first.**      
143f0 20 20 20 20 20 63 6f 70 69 65 73 20 74 68 65 20       copies the 
14400 66 69 72 73 74 20 4b 20 62 79 74 65 73 20 6f 66  first K bytes of
14410 20 63 6f 6e 74 65 6e 74 20 66 72 6f 6d 20 50 20   content from P 
14420 69 6e 74 6f 20 74 68 65 20 6e 65 77 6c 79 0a 2a  into the newly.*
14430 2a 20 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f  *           allo
14440 63 61 74 65 64 20 62 6c 6f 63 6b 2c 20 77 68 65  cated block, whe
14450 72 65 20 4b 20 69 73 20 74 68 65 20 6c 65 73 73  re K is the less
14460 65 72 20 6f 66 20 4e 20 61 6e 64 20 74 68 65 20  er of N and the 
14470 73 69 7a 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20  size of.**      
14480 20 20 20 20 20 74 68 65 20 62 75 66 66 65 72 20       the buffer 
14490 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 32 32  P..**.** {F17322
144a0 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  }  When [sqlite3
144b0 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72  _realloc(P,N)] r
144c0 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c  eturns a non-NUL
144d0 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69  L pointer, it fi
144e0 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rst.**          
144f0 20 72 65 6c 65 61 73 65 73 20 74 68 65 20 62 75   releases the bu
14500 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ffer P..**.** {F
14510 31 37 33 32 33 7d 20 20 57 68 65 6e 20 5b 73 71  17323}  When [sq
14520 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c  lite3_realloc(P,
14530 4e 29 5d 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  N)] returns NULL
14540 2c 20 74 68 65 20 62 75 66 66 65 72 20 50 20 69  , the buffer P i
14550 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e  s.**           n
14560 6f 74 20 6d 6f 64 69 66 69 65 64 20 6f 72 20 72  ot modified or r
14570 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 4c  eleased..**.** L
14580 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  IMITATIONS:.**.*
14590 2a 20 7b 55 31 37 33 35 30 7d 20 20 54 68 65 20  * {U17350}  The 
145a0 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
145b0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
145c0 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
145d0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
145e0 20 20 20 20 20 20 20 20 20 20 20 6d 75 73 74 20             must 
145f0 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
14600 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
14610 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
14620 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  prior.**        
14630 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66     invocation of
14640 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
14650 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
14660 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
14670 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  have.**         
14680 20 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72    not yet been r
14690 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  eleased..**.** {
146a0 55 31 37 33 35 31 7d 20 20 54 68 65 20 61 70 70  U17351}  The app
146b0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
146c0 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
146d0 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 20  any part of.**  
146e0 20 20 20 20 20 20 20 20 20 61 20 62 6c 6f 63 6b           a block
146f0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
14700 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
14710 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20  eased using.**  
14720 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
14730 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
14740 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
14750 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
14760 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
14770 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
14780 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
14790 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
147a0 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  free(void*);../*
147b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
147c0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
147d0 74 61 74 69 73 74 69 63 73 20 7b 46 31 37 33 37  tatistics {F1737
147e0 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  0}.**.** SQLite 
147f0 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74  provides these t
14800 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f  wo interfaces fo
14810 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74  r reporting on t
14820 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20  he status.** of 
14830 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  the [sqlite3_mal
14840 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
14850 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
14860 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
14870 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77  ].** routines, w
14880 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75  hich form the bu
14890 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
148a0 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
148b0 65 6d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  em..**.** INVARI
148c0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  ANTS:.**.** {F17
148d0 33 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  371} The [sqlite
148e0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
148f0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
14900 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
14910 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ytes.**         
14920 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
14930 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
14940 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
14950 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 0a 2a 2a  ot freed)..**.**
14960 20 7b 46 31 37 33 37 33 7d 20 54 68 65 20 5b 73   {F17373} The [s
14970 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
14980 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69  ghwater()] routi
14990 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d  ne returns the m
149a0 61 78 69 6d 75 6d 0a 2a 2a 20 20 20 20 20 20 20  aximum.**       
149b0 20 20 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c     value of [sql
149c0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
149d0 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
149e0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
149f0 20 20 20 20 20 20 20 20 20 20 77 61 73 20 6c 61            was la
14a00 73 74 20 72 65 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  st reset..**.** 
14a10 7b 46 31 37 33 37 34 7d 20 54 68 65 20 76 61 6c  {F17374} The val
14a20 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
14a30 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
14a40 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20  used()] and.**  
14a50 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
14a60 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
14a70 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79  r()] include any
14a80 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 20 20 20   overhead.**    
14a90 20 20 20 20 20 20 61 64 64 65 64 20 62 79 20 53        added by S
14aa0 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70  QLite in its imp
14ab0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
14ac0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14ad0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  ],.**          b
14ae0 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
14af0 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79  added by the any
14b00 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74   underlying syst
14b10 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 20 20  em library.**   
14b20 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65 73 20         routines 
14b30 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61  that [sqlite3_ma
14b40 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c  lloc()] may call
14b50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37 35 7d  ..**.** {F17375}
14b60 20 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68   The memory high
14b70 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
14b80 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
14b90 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
14ba0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
14bb0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
14bc0 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
14bd0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  the parameter to
14be0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
14bf0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
14c00 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
14c10 65 2e 20 20 54 68 65 20 76 61 6c 75 65 20 72 65  e.  The value re
14c20 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20  turned.**       
14c30 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d     by [sqlite3_m
14c40 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
14c50 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
14c60 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20  water mark.**   
14c70 20 20 20 20 20 20 20 70 72 69 6f 72 20 74 6f 20         prior to 
14c80 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71  the reset..*/.sq
14c90 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
14ca0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
14cb0 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69  void);.sqlite3_i
14cc0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
14cd0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
14ce0 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
14cf0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
14d00 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
14d10 62 65 72 20 47 65 6e 65 72 61 74 6f 72 20 7b 46  ber Generator {F
14d20 31 37 33 39 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  17390}.**.** SQL
14d30 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68  ite contains a h
14d40 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
14d50 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72  do-random number
14d60 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47   generator (PRNG
14d70 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c  ) used to.** sel
14d80 65 63 74 20 72 61 6e 64 6f 6d 20 52 4f 57 49 44  ect random ROWID
14d90 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  s when inserting
14da0 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
14db0 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
14dc0 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
14dd0 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
14de0 62 6c 65 20 52 4f 57 49 44 2e 20 20 54 68 65 20  ble ROWID.  The 
14df0 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
14e00 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
14e10 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
14e20 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
14e30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
14e40 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
14e50 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
14e60 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
14e70 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
14e80 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
14e90 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
14ea0 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73  o this routine s
14eb0 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66  tores N bytes of
14ec0 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
14ed0 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a   buffer P..**.**
14ee0 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   The first time 
14ef0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
14f00 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20  invoked (either 
14f10 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79  internally or by
14f20 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
14f30 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73  ion) the PRNG is
14f40 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61   seeded using ra
14f50 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
14f60 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52  d.** from the xR
14f70 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64  andomness method
14f80 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
14f90 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
14fa0 6a 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20  ject..** On all 
14fb0 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
14fc0 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75  ations, the pseu
14fd0 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
14fe0 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
14ff0 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
15000 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
15010 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
15020 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
15030 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20  * method..**.** 
15040 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
15050 2a 20 7b 46 31 37 33 39 32 7d 20 54 68 65 20 5b  * {F17392} The [
15060 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
15070 73 73 28 4e 2c 50 29 5d 20 69 6e 74 65 72 66 61  ss(N,P)] interfa
15080 63 65 20 77 72 69 74 65 73 20 4e 20 62 79 74 65  ce writes N byte
15090 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  s of.**         
150a0 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73   high-quality ps
150b0 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20  eudo-randomness 
150c0 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
150d0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
150e0 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c  andomness(int N,
150f0 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a   void *P);../*.*
15100 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
15110 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69  ile-Time Authori
15120 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  zation Callbacks
15130 20 7b 46 31 32 35 30 30 7d 0a 2a 2a 0a 2a 2a 20   {F12500}.**.** 
15140 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
15150 69 73 74 65 72 73 20 61 20 61 75 74 68 6f 72 69  isters a authori
15160 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74  zer callback wit
15170 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
15180 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
15190 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65  ection], supplie
151a0 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
151b0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  rgument..** The 
151c0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
151d0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ack is invoked a
151e0 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  s SQL statements
151f0 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69   are being compi
15200 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  led.** by [sqlit
15210 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
15220 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73   its variants [s
15230 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
15240 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
15250 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61  3_prepare16()] a
15260 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
15270 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 41 74  are16_v2()].  At
15280 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e   various.** poin
15290 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f  ts during the co
152a0 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73  mpilation proces
152b0 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62  s, as logic is b
152c0 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20  eing created.** 
152d0 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
152e0 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  us actions, the 
152f0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
15300 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  ack is invoked t
15310 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73  o.** see if thos
15320 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  e actions are al
15330 6c 6f 77 65 64 2e 20 20 54 68 65 20 61 75 74 68  lowed.  The auth
15340 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
15350 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
15360 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20   [SQLITE_OK] to 
15370 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e  allow the action
15380 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  , [SQLITE_IGNORE
15390 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68  ] to disallow th
153a0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63  e.** specific ac
153b0 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74  tion but allow t
153c0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
153d0 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   to continue to 
153e0 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20  be.** compiled, 
153f0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
15400 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e   to cause the en
15410 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  tire SQL stateme
15420 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65  nt to be.** reje
15430 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72  cted with an err
15440 6f 72 2e 20 20 49 66 20 74 68 65 20 61 75 74 68  or.  If the auth
15450 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
15460 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76  returns.** any v
15470 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
15480 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
15490 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
154a0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a   [SQLITE_DENY].*
154b0 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  * then the [sqli
154c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
154d0 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
154e0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
154f0 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
15500 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
15510 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
15520 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ssage..**.** Whe
15530 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
15540 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
15550 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
15560 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
15570 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
15580 20 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62    When the callb
15590 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
155a0 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
155b0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
155c0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
155d0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
155e0 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a   triggered the.*
155f0 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  * authorizer wil
15600 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
15610 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70  rror message exp
15620 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20  laining that.** 
15630 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64  access is denied
15640 2e 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72  .  If the author
15650 69 7a 65 72 20 63 6f 64 65 20 69 73 20 5b 53 51  izer code is [SQ
15660 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
15670 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
15680 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
15690 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
156a0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
156b0 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
156c0 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
156d0 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
156e0 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
156f0 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
15700 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
15710 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
15720 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
15730 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
15740 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
15750 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
15760 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
15770 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
15780 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
15790 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
157a0 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
157b0 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a  of a table..**.*
157c0 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
157d0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
157e0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
157f0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
15800 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
15810 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
15820 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
15830 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
15840 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
15850 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
15860 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
15870 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f  teger [SQLITE_CO
15880 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65  PY | action code
15890 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
158a0 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c  .** the particul
158b0 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  ar action to be 
158c0 61 75 74 68 6f 72 69 7a 65 64 2e 20 54 68 65 20  authorized. The 
158d0 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
158e0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  xth parameters.*
158f0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
15900 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  k are zero-termi
15910 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
15920 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
15930 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73  ional.** details
15940 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
15950 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
15960 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74  ed..**.** An aut
15970 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20  horizer is used 
15980 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  when [sqlite3_pr
15990 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e  epare | preparin
159a0 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  g].** SQL statem
159b0 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74  ents from an unt
159c0 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74  rusted source, t
159d0 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  o ensure that th
159e0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
159f0 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  .** do not try t
15a00 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68  o access data th
15a10 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77  ey are not allow
15a20 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68  ed to see, or th
15a30 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
15a40 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65  * try to execute
15a50 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65   malicious state
15a60 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67  ments that damag
15a70 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  e the database. 
15a80 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
15a90 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
15aa0 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72  may allow a user
15ab0 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72   to enter arbitr
15ac0 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69  ary.** SQL queri
15ad0 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f  es for evaluatio
15ae0 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e  n by a database.
15af0 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63    But the applic
15b00 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ation does.** no
15b10 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20  t want the user 
15b20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61  to be able to ma
15b30 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61  ke arbitrary cha
15b40 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  nges to the.** d
15b50 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74  atabase.  An aut
15b60 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68  horizer could th
15b70 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61  en be put in pla
15b80 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20  ce while the.** 
15b90 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
15ba0 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74   is being [sqlit
15bb0 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
15bc0 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64  pared] that.** d
15bd0 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68  isallows everyth
15be0 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45  ing except [SELE
15bf0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  CT] statements..
15c00 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
15c10 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20  ns that need to 
15c20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d  process SQL from
15c30 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
15c40 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f  es.** might also
15c50 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69   consider loweri
15c60 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69  ng resource limi
15c70 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ts using [sqlite
15c80 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e  3_limit()].** an
15c90 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62  d limiting datab
15ca0 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74  ase size using t
15cb0 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  he [max_page_cou
15cc0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20  nt] [PRAGMA].** 
15cd0 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75  in addition to u
15ce0 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a  sing an authoriz
15cf0 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61  er..**.** Only a
15d00 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
15d10 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
15d20 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
15d30 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
15d40 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
15d50 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
15d60 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
15d70 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
15d80 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20  previous call.  
15d90 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68  Disable the auth
15da0 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c  orizer by instal
15db0 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c  ling a NULL call
15dc0 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74  back..** The aut
15dd0 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62  horizer is disab
15de0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
15df0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
15e00 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
15e10 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
15e20 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
15e30 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
15e40 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
15e50 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
15e60 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
15e70 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
15e80 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
15e90 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
15ea0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_step()]..**.**
15eb0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
15ec0 2a 2a 20 7b 46 31 32 35 30 31 7d 20 54 68 65 20  ** {F12501} The 
15ed0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
15ee0 68 6f 72 69 7a 65 72 28 44 2c 2e 2e 2e 29 5d 20  horizer(D,...)] 
15ef0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
15f00 65 72 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20  ers a.**        
15f10 20 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c    authorizer cal
15f20 6c 62 61 63 6b 20 77 69 74 68 20 64 61 74 61 62  lback with datab
15f30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
15f40 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30 32 7d  ..**.** {F12502}
15f50 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
15f60 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
15f70 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
15f80 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 20 20 20  ments are.**    
15f90 20 20 20 20 20 20 62 65 69 6e 67 20 63 6f 6d 70        being comp
15fa0 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  iled..**.** {F12
15fb0 35 30 33 7d 20 49 66 20 74 68 65 20 61 75 74 68  503} If the auth
15fc0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
15fd0 72 65 74 75 72 6e 73 20 61 6e 79 20 76 61 6c 75  returns any valu
15fe0 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20  e other than.** 
15ff0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
16000 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
16010 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
16020 45 5f 44 45 4e 59 5d 2c 20 74 68 65 6e 0a 2a 2a  E_DENY], then.**
16030 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73            the [s
16040 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
16050 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
16060 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 63 61 75  nt call that cau
16070 73 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  sed.**          
16080 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
16090 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 73  allback to run s
160a0 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  hall fail with a
160b0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  n.**          [S
160c0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72  QLITE_ERROR] err
160d0 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 61  or code and an a
160e0 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
160f0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
16100 7b 46 31 32 35 30 34 7d 20 57 68 65 6e 20 74 68  {F12504} When th
16110 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
16120 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
16130 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 20 6f  QLITE_OK], the o
16140 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  peration.**     
16150 20 20 20 20 20 64 65 73 63 72 69 62 65 64 20 69       described i
16160 73 20 70 72 6f 63 65 73 73 65 64 20 6e 6f 72 6d  s processed norm
16170 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ally..**.** {F12
16180 35 30 35 7d 20 57 68 65 6e 20 74 68 65 20 61 75  505} When the au
16190 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
161a0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
161b0 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
161c0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
161d0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
161e0 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
161f0 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64 20 74  ll that caused t
16200 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  he.**          a
16210 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
16220 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20  ck to run shall 
16230 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  fail.**         
16240 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45   with an [SQLITE
16250 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f  _ERROR] error co
16260 64 65 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20  de and an error 
16270 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20  message.**      
16280 20 20 20 20 65 78 70 6c 61 69 6e 69 6e 67 20 74      explaining t
16290 68 61 74 20 61 63 63 65 73 73 20 69 73 20 64 65  hat access is de
162a0 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  nied..**.** {F12
162b0 35 30 36 7d 20 49 66 20 74 68 65 20 61 75 74 68  506} If the auth
162c0 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65  orizer code (the
162d0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
162e0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
162f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
16300 6c 62 61 63 6b 29 20 69 73 20 5b 53 51 4c 49 54  lback) is [SQLIT
16310 45 5f 52 45 41 44 5d 20 61 6e 64 20 74 68 65 20  E_READ] and the 
16320 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
16330 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ack returns.**  
16340 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
16350 49 47 4e 4f 52 45 5d 2c 20 74 68 65 6e 20 74 68  IGNORE], then th
16360 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
16370 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
16380 74 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ted to.**       
16390 20 20 20 69 6e 73 65 72 74 20 61 20 4e 55 4c 4c     insert a NULL
163a0 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
163b0 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
163c0 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
163d0 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ave.**          
163e0 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
163f0 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
16400 6e 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  n returned..**.*
16410 2a 20 7b 46 31 32 35 30 37 7d 20 49 66 20 74 68  * {F12507} If th
16420 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64  e authorizer cod
16430 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d  e (the 2nd param
16440 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
16450 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20  orizer.**       
16460 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20     callback) is 
16470 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 20 74  anything other t
16480 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45 41 44  han [SQLITE_READ
16490 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  ], then.**      
164a0 20 20 20 20 61 20 72 65 74 75 72 6e 20 6f 66 20      a return of 
164b0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
164c0 68 61 73 20 74 68 65 20 73 61 6d 65 20 65 66 66  has the same eff
164d0 65 63 74 20 61 73 20 5b 53 51 4c 49 54 45 5f 44  ect as [SQLITE_D
164e0 45 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ENY]..**.** {F12
164f0 35 31 30 7d 20 54 68 65 20 66 69 72 73 74 20 70  510} The first p
16500 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
16510 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
16520 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
16530 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
16540 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
16550 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
16560 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
16570 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
16580 0a 2a 2a 20 7b 46 31 32 35 31 31 7d 20 54 68 65  .** {F12511} The
16590 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
165a0 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
165b0 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  k is an integer.
165c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
165d0 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
165e0 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
165f0 63 69 66 69 65 73 20 74 68 65 20 70 61 72 74 69  cifies the parti
16600 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20  cular action.** 
16610 20 20 20 20 20 20 20 20 20 74 6f 20 62 65 20 61           to be a
16620 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
16630 20 7b 46 31 32 35 31 32 7d 20 54 68 65 20 74 68   {F12512} The th
16640 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
16650 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
16660 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
16670 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
16680 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
16690 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
166a0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64  n.**          ad
166b0 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73  ditional details
166c0 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
166d0 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
166e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32  ed..**.** {F1252
166f0 30 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  0} Each call to 
16700 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
16710 68 6f 72 69 7a 65 72 28 29 5d 20 6f 76 65 72 72  horizer()] overr
16720 69 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ides.**         
16730 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20   any previously 
16740 69 6e 73 74 61 6c 6c 65 64 20 61 75 74 68 6f 72  installed author
16750 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  izer..**.** {F12
16760 35 32 31 7d 20 41 20 4e 55 4c 4c 20 61 75 74 68  521} A NULL auth
16770 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20 74 68 61  orizer means tha
16780 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61 74 69  t no authorizati
16790 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  on.**          c
167a0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
167b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 32  ed..**.** {F1252
167c0 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 61  2} The default a
167d0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c  uthorizer is NUL
167e0 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
167f0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
16800 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
16810 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
16820 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
16830 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
16840 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
16850 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
16860 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
16870 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
16880 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
16890 20 43 6f 64 65 73 20 7b 46 31 32 35 39 30 7d 0a   Codes {F12590}.
168a0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
168b0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
168c0 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
168d0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
168e0 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
168f0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
16900 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
16910 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
16920 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
16930 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
16940 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
16950 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
16960 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
16970 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
16980 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
16990 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
169a0 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
169b0 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
169c0 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  tion..*/.#define
169d0 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31   SQLITE_DENY   1
169e0 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20     /* Abort the 
169f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69  SQL statement wi
16a00 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23  th an error */.#
16a10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47  define SQLITE_IG
16a20 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27  NORE 2   /* Don'
16a30 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20  t allow access, 
16a40 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61  but don't genera
16a50 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a  te an error */..
16a60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
16a70 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f  Authorizer Actio
16a80 6e 20 43 6f 64 65 73 20 7b 46 31 32 35 35 30 7d  n Codes {F12550}
16a90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
16aa0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
16ab0 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
16ac0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
16ad0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
16ae0 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
16af0 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
16b00 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
16b10 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
16b20 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
16b30 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
16b40 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
16b50 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
16b60 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
16b70 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
16b80 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
16b90 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
16ba0 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
16bb0 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
16bc0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
16bd0 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
16be0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
16bf0 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
16c00 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
16c10 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
16c20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
16c30 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
16c40 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
16c50 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
16c60 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
16c70 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
16c80 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
16c90 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
16ca0 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
16cb0 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
16cc0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
16cd0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
16ce0 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
16cf0 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
16d00 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
16d10 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
16d20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
16d30 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
16d40 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
16d50 2e 20 20 54 68 65 20 36 74 68 20 70 61 72 61 6d  .  The 6th param
16d60 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
16d70 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
16d80 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
16d90 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
16da0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
16db0 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
16dc0 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
16dd0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
16de0 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
16df0 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
16e00 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
16e10 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
16e20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  code..**.** INVA
16e30 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
16e40 31 32 35 35 31 7d 20 54 68 65 20 73 65 63 6f 6e  12551} The secon
16e50 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 61  d parameter to a
16e60 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  n.**          [s
16e70 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
16e80 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
16e90 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20  er callback] is 
16ea0 61 6c 77 61 79 73 20 61 6e 20 69 6e 74 65 67 65  always an intege
16eb0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  r.**          [S
16ec0 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75 74  QLITE_COPY | aut
16ed0 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 74 68  horizer code] th
16ee0 61 74 20 73 70 65 63 69 66 69 65 73 20 77 68 61  at specifies wha
16ef0 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  t action.**     
16f00 20 20 20 20 20 69 73 20 62 65 69 6e 67 20 61 75       is being au
16f10 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
16f20 7b 46 31 32 35 35 32 7d 20 54 68 65 20 33 72 64  {F12552} The 3rd
16f30 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
16f40 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ers to the.**   
16f50 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
16f60 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
16f70 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63   authorization c
16f80 61 6c 6c 62 61 63 6b 5d 0a 2a 2a 20 20 20 20 20  allback].**     
16f90 20 20 20 20 20 77 69 6c 6c 20 62 65 20 70 61 72       will be par
16fa0 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
16fb0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
16fc0 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ch.**          [
16fd0 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75  SQLITE_COPY | au
16fe0 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 69  thorizer code] i
16ff0 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
17000 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a  cond parameter..
17010 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 33 7d 20 54  **.** {F12553} T
17020 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
17030 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   to the.**      
17040 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74      [sqlite3_set
17050 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
17060 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17070 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d 65 0a 2a  k] is the name.*
17080 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
17090 65 20 64 61 74 61 62 61 73 65 20 28 65 78 61 6d  e database (exam
170a0 70 6c 65 3a 20 22 6d 61 69 6e 22 2c 20 22 74 65  ple: "main", "te
170b0 6d 70 22 2c 20 65 74 63 2e 29 20 69 66 20 61 70  mp", etc.) if ap
170c0 70 6c 69 63 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  plicable..**.** 
170d0 7b 46 31 32 35 35 34 7d 20 54 68 65 20 36 74 68  {F12554} The 6th
170e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
170f0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
17100 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
17110 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
17120 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20  er callback] is 
17130 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20  the name.**     
17140 20 20 20 20 20 6f 66 20 74 68 65 20 69 6e 6e 65       of the inne
17150 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
17160 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
17170 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
17180 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61  *          the a
17190 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
171a0 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
171b0 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
171c0 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
171d0 20 20 20 20 20 20 20 20 20 20 74 6f 70 2d 6c 65            top-le
171e0 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
171f0 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
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 20 33 72  ************* 3r
17220 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
17230 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
17240 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17250 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
17260 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
17270 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
17280 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
17290 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
172a0 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
172b0 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
172c0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
172d0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
172e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
172f0 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
17300 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
17310 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
17320 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
17330 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
17340 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
17350 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
17360 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
17370 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
17380 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
17390 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
173a0 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
173b0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
173c0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
173d0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
173e0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
173f0 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
17400 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
17410 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
17420 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
17430 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
17440 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
17450 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
17460 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
17470 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
17480 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
17490 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
174a0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
174b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
174c0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
174d0 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
174e0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
174f0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
17500 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
17510 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
17520 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
17530 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
17540 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
17550 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17560 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
17570 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
17580 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
17590 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
175a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
175b0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
175c0 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
175d0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
175e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
175f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17600 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
17610 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
17620 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
17630 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
17640 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17650 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
17660 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
17670 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
17680 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
17690 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
176a0 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
176b0 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
176c0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
176d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
176e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
176f0 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
17700 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
17710 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
17720 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
17730 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17740 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
17750 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
17760 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
17770 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
17780 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
17790 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
177a0 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
177b0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
177c0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
177d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
177e0 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
177f0 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
17800 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
17810 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
17820 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
17830 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
17840 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
17850 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
17860 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
17870 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
17880 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
17890 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
178a0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
178b0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
178c0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
178d0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
178e0 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  2   /* NULL     
178f0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
17900 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
17910 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
17920 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
17930 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
17940 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
17950 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
17960 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
17970 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
17980 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
17990 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
179a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
179b0 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
179c0 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
179d0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
179e0 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
179f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
17a00 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
17a10 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
17a20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
17a30 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
17a40 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17a50 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
17a60 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
17a70 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
17a80 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
17a90 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17aa0 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
17ab0 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
17ac0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
17ad0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
17ae0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17af0 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
17b00 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
17b10 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
17b20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
17b30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17b40 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
17b50 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
17b60 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
17b70 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
17b80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17b90 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
17ba0 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 46 75        31   /* Fu
17bb0 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 4e 55  nction Name   NU
17bc0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
17bd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17be0 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
17bf0 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
17c00 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a  longer used */..
17c10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17c20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
17c30 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20  iling Functions 
17c40 7b 46 31 32 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12280}.**.** T
17c50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
17c60 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
17c70 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
17c80 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
17c90 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
17ca0 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
17cb0 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
17cc0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  tements..**.** T
17cd0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
17ce0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
17cf0 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
17d00 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
17d10 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
17d20 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
17d30 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
17d40 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
17d50 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65  _step()]..** The
17d60 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
17d70 73 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  s a UTF-8 render
17d80 69 6e 67 20 6f 66 20 74 68 65 20 53 51 4c 20 73  ing of the SQL s
17d90 74 61 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a  tatement text.**
17da0 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
17db0 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
17dc0 78 65 63 75 74 69 6e 67 2e 20 20 41 64 64 69 74  xecuting.  Addit
17dd0 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20  ional callbacks 
17de0 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68  occur.** as each
17df0 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72   triggered subpr
17e00 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64  ogram is entered
17e10 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73  .  The callbacks
17e20 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a   for triggers.**
17e30 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38   contain a UTF-8
17e40 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61   SQL comment tha
17e50 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  t identifies the
17e60 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   trigger..**.** 
17e70 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
17e80 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
17e90 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66   by sqlite3_prof
17ea0 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ile() is invoked
17eb0 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20  .** as each SQL 
17ec0 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
17ed0 65 73 2e 20 20 54 68 65 20 70 72 6f 66 69 6c 65  es.  The profile
17ee0 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
17ef0 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  ns.** the origin
17f00 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  al statement tex
17f10 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74  t and an estimat
17f20 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  e of wall-clock 
17f30 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c  time.** of how l
17f40 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
17f50 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a  nt took to run..
17f60 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
17f70 33 5f 70 72 6f 66 69 6c 65 28 29 20 41 50 49 20  3_profile() API 
17f80 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e  is currently con
17f90 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65  sidered experime
17fa0 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20 69 73 20 73  ntal and.** is s
17fb0 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
17fc0 20 6f 72 20 72 65 6d 6f 76 61 6c 20 69 6e 20 61   or removal in a
17fd0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 2e   future release.
17fe0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 72 69 67 67  .**.** The trigg
17ff0 65 72 20 72 65 70 6f 72 74 69 6e 67 20 66 65 61  er reporting fea
18000 74 75 72 65 20 6f 66 20 74 68 65 20 74 72 61 63  ture of the trac
18010 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 6f  e callback is co
18020 6e 73 69 64 65 72 65 64 0a 2a 2a 20 65 78 70 65  nsidered.** expe
18030 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20  rimental and is 
18040 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
18050 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 69 6e 20  e or removal in 
18060 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
18070 0a 2a 2a 20 46 75 74 75 72 65 20 76 65 72 73 69  .** Future versi
18080 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
18090 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6e 65 77  ght also add new
180a0 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a   trace callback.
180b0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2e 0a  ** invocations..
180c0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
180d0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 31 7d  :.**.** {F12281}
180e0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
180f0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
18100 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 72  d by [sqlite3_tr
18110 61 63 65 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20  ace()] is.**    
18120 20 20 20 20 20 20 77 68 65 6e 65 76 65 72 20 61        whenever a
18130 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
18140 66 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20  first begins to 
18150 65 78 65 63 75 74 65 20 61 6e 64 0a 2a 2a 20 20  execute and.**  
18160 20 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 72          whenever
18170 20 61 20 74 72 69 67 67 65 72 20 73 75 62 70 72   a trigger subpr
18180 6f 67 72 61 6d 20 66 69 72 73 74 20 62 65 67 69  ogram first begi
18190 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  ns to run..**.**
181a0 20 7b 46 31 32 32 38 32 7d 20 45 61 63 68 20 63   {F12282} Each c
181b0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
181c0 74 72 61 63 65 28 29 5d 20 6f 76 65 72 72 69 64  trace()] overrid
181d0 65 73 20 74 68 65 20 70 72 65 76 69 6f 75 73 6c  es the previousl
181e0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  y.**          re
181f0 67 69 73 74 65 72 65 64 20 74 72 61 63 65 20 63  gistered trace c
18200 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b  allback..**.** {
18210 46 31 32 32 38 33 7d 20 41 20 4e 55 4c 4c 20 74  F12283} A NULL t
18220 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 64 69  race callback di
18230 73 61 62 6c 65 73 20 74 72 61 63 69 6e 67 2e 0a  sables tracing..
18240 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 34 7d 20 54  **.** {F12284} T
18250 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18260 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63  t to the trace c
18270 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
18280 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  y of.**         
18290 20 74 68 65 20 70 6f 69 6e 74 65 72 20 77 68 69   the pointer whi
182a0 63 68 20 77 61 73 20 74 68 65 20 33 72 64 20 61  ch was the 3rd a
182b0 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
182c0 74 65 33 5f 74 72 61 63 65 28 29 5d 2e 0a 2a 2a  te3_trace()]..**
182d0 0a 2a 2a 20 7b 46 31 32 32 38 35 7d 20 54 68 65  .** {F12285} The
182e0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
182f0 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61   to the trace ca
18300 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20  llback is a.**  
18310 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72          zero-ter
18320 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
18330 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
18340 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 74 65 78  the original tex
18350 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  t.**          of
18360 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
18370 6e 74 20 61 73 20 69 74 20 77 61 73 20 70 61 73  nt as it was pas
18380 73 65 64 20 69 6e 74 6f 20 5b 73 71 6c 69 74 65  sed into [sqlite
18390 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a  3_prepare_v2()].
183a0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74  **          or t
183b0 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f  he equivalent, o
183c0 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  r an SQL comment
183d0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20   indicating the 
183e0 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20  beginning.**    
183f0 20 20 20 20 20 20 6f 66 20 61 20 74 72 69 67 67        of a trigg
18400 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 0a 2a  er subprogram..*
18410 2a 0a 2a 2a 20 7b 46 31 32 32 38 37 7d 20 54 68  *.** {F12287} Th
18420 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
18430 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
18440 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  y [sqlite3_profi
18450 6c 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64  le()] is invoked
18460 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20  .**          as 
18470 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
18480 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a  nt finishes..**.
18490 2a 2a 20 7b 46 31 32 32 38 38 7d 20 54 68 65 20  ** {F12288} The 
184a0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
184b0 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63  to the profile c
184c0 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
184d0 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  y of.**         
184e0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
184f0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  er to [sqlite3_p
18500 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  rofile()]..**.**
18510 20 7b 46 31 32 32 38 39 7d 20 54 68 65 20 73 65   {F12289} The se
18520 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
18530 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61  o the profile ca
18540 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20  llback is a.**  
18550 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72          zero-ter
18560 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
18570 72 69 6e 67 20 74 68 61 74 20 63 6f 6e 74 61 69  ring that contai
18580 6e 73 20 74 68 65 20 63 6f 6d 70 6c 65 74 65 20  ns the complete 
18590 74 65 78 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20  text of.**      
185a0 20 20 20 20 74 68 65 20 53 51 4c 20 73 74 61 74      the SQL stat
185b0 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73 20  ement as it was 
185c0 70 72 6f 63 65 73 73 65 64 20 62 79 20 5b 73 71  processed by [sq
185d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
185e0 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
185f0 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  or the equivalen
18600 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 39 30  t..**.** {F12290
18610 7d 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61  } The third para
18620 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f  meter to the pro
18630 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  file callback is
18640 20 61 6e 20 65 73 74 69 6d 61 74 65 0a 2a 2a 20   an estimate.** 
18650 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
18660 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65  number of nanose
18670 63 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d 63 6c  conds of wall-cl
18680 6f 63 6b 20 74 69 6d 65 20 72 65 71 75 69 72 65  ock time require
18690 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  d to.**         
186a0 20 72 75 6e 20 74 68 65 20 53 51 4c 20 73 74 61   run the SQL sta
186b0 74 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74 61 72  tement from star
186c0 74 20 74 6f 20 66 69 6e 69 73 68 2e 0a 2a 2f 0a  t to finish..*/.
186d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
186e0 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
186f0 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
18700 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
18710 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71  void*);.void *sq
18720 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
18730 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
18740 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
18750 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
18760 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
18770 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
18780 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
18790 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 20  gress Callbacks 
187a0 7b 46 31 32 39 31 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12910}.**.** T
187b0 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66  his routine conf
187c0 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63  igures a callbac
187d0 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65  k function - the
187e0 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c  .** progress cal
187f0 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20  lback - that is 
18800 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
18810 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
18820 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  .** running call
18830 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78  s to [sqlite3_ex
18840 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
18850 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  step()] and.** [
18860 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
18870 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c  e()].  An exampl
18880 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a  e use for this.*
18890 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
188a0 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64  o keep a GUI upd
188b0 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61  ated during a la
188c0 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a  rge query..**.**
188d0 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73   If the progress
188e0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
188f0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
18900 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
18910 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
18920 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
18930 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
18940 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
18950 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
18960 49 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  I dialog box..**
18970 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
18980 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 31 7d 20 54  **.** {F12911} T
18990 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
189a0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
189b0 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  by sqlite3_progr
189c0 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a  ess_handler().**
189d0 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76            is inv
189e0 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
189f0 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75  y during long ru
18a00 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a  nning calls to.*
18a10 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
18a20 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
18a30 2a 2a 20 7b 46 31 32 39 31 32 7d 20 54 68 65 20  ** {F12912} The 
18a40 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
18a50 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  k is invoked onc
18a60 65 20 66 6f 72 20 65 76 65 72 79 20 4e 20 76 69  e for every N vi
18a70 72 74 75 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20  rtual.**        
18a80 20 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f 64 65    machine opcode
18a90 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  s, where N is th
18aa0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
18ab0 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  t to.**         
18ac0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
18ad0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29  ogress_handler()
18ae0 5d 20 63 61 6c 6c 20 74 68 61 74 20 72 65 67 69  ] call that regi
18af0 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20  stered.**       
18b00 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e     the callback.
18b10 20 20 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74    If N is less t
18b20 68 61 6e 20 31 2c 20 73 71 6c 69 74 65 33 5f 70  han 1, sqlite3_p
18b30 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
18b40 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 63  ).**          ac
18b50 74 73 20 61 73 20 69 66 20 61 20 4e 55 4c 4c 20  ts as if a NULL 
18b60 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
18b70 20 68 61 64 20 62 65 65 6e 20 73 70 65 63 69 66   had been specif
18b80 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ied..**.** {F129
18b90 31 33 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73  13} The progress
18ba0 20 63 61 6c 6c 62 61 63 6b 20 69 74 73 65 6c 66   callback itself
18bb0 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62   is identified b
18bc0 79 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 20  y the third.**  
18bd0 20 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74          argument
18be0 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67   to sqlite3_prog
18bf0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 2e 0a  ress_handler()..
18c00 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 34 7d 20 54  **.** {F12914} T
18c10 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
18c20 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72  nt to sqlite3_pr
18c30 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29  ogress_handler()
18c40 20 69 73 20 61 0a 2a 2a 2a 20 20 20 20 20 20 20   is a.***       
18c50 20 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 70    void pointer p
18c60 61 73 73 65 64 20 74 6f 20 74 68 65 20 70 72 6f  assed to the pro
18c70 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a  gress callback.*
18c80 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74  *          funct
18c90 69 6f 6e 20 65 61 63 68 20 74 69 6d 65 20 69 74  ion each time it
18ca0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
18cb0 2a 2a 20 7b 46 31 32 39 31 35 7d 20 49 66 20 61  ** {F12915} If a
18cc0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
18cd0 33 5f 73 74 65 70 28 29 5d 20 72 65 73 75 6c 74  3_step()] result
18ce0 73 20 69 6e 20 66 65 77 65 72 20 74 68 61 6e 0a  s in fewer than.
18cf0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 20 6f 70  **          N op
18d00 63 6f 64 65 73 20 62 65 69 6e 67 20 65 78 65 63  codes being exec
18d10 75 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20  uted,.**        
18d20 20 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72    then the progr
18d30 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ess callback is 
18d40 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64 2e 20 7b  never invoked. {
18d50 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  END}.**.** {F129
18d60 31 36 7d 20 45 76 65 72 79 20 63 61 6c 6c 20 74  16} Every call t
18d70 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  o [sqlite3_progr
18d80 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a 2a  ess_handler()].*
18d90 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65 72 77  *          overw
18da0 72 69 74 65 73 20 61 6e 79 20 70 72 65 76 69 6f  rites any previo
18db0 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 20  usly registered 
18dc0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
18dd0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 37 7d  ..**.** {F12917}
18de0 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73   If the progress
18df0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
18e00 6b 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 6e  k is NULL then n
18e10 6f 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 20 20  o progress.**   
18e20 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20 69         handler i
18e30 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
18e40 20 7b 46 31 32 39 31 38 7d 20 49 66 20 74 68 65   {F12918} If the
18e50 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
18e60 63 6b 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  ck returns a res
18e70 75 6c 74 20 6f 74 68 65 72 20 74 68 61 6e 20 30  ult other than 0
18e80 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
18e90 20 20 20 74 68 65 20 62 65 68 61 76 69 6f 72 20     the behavior 
18ea0 69 73 20 61 20 69 66 20 5b 73 71 6c 69 74 65 33  is a if [sqlite3
18eb0 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20 68 61  _interrupt()] ha
18ec0 64 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a  d been called..*
18ed0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  /.void sqlite3_p
18ee0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
18ef0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
18f00 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
18f10 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
18f20 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
18f30 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
18f40 6e 6e 65 63 74 69 6f 6e 20 7b 46 31 32 37 30 30  nnection {F12700
18f50 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  }.**.** These ro
18f60 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
18f70 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
18f80 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69  ile whose name i
18f90 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a  s given by the.*
18fa0 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
18fb0 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e 61 6d  ent. The filenam
18fc0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
18fd0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
18fe0 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
18ff0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
19000 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
19010 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
19020 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
19030 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
19040 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 41  ite3_open16(). A
19050 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
19060 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
19070 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
19080 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
19090 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
190a0 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
190b0 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
190c0 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
190d0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
190e0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
190f0 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
19100 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
19110 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
19120 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
19130 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
19140 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
19150 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
19160 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  . If the databas
19170 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
19180 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
19190 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
191a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
191b0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
191c0 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
191d0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
191e0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  ed.  The.** [sql
191f0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
19200 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
19210 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
19220 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
19230 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
19240 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
19250 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
19260 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  error..**.** The
19270 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
19280 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  g for the databa
19290 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  se will be UTF-8
192a0 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   if.** sqlite3_o
192b0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
192c0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61  _open_v2() is ca
192d0 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d  lled and.** UTF-
192e0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
192f0 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73   byte order if s
19300 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
19310 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57  is used..**.** W
19320 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
19330 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
19340 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
19350 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
19360 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
19370 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
19380 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
19390 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
193a0 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
193b0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
193c0 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
193d0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
193e0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
193f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
19400 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
19410 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
19420 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
19430 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
19440 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
19450 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
19460 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
19470 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
19480 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
19490 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67  ction.  The flag
194a0 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20  s parameter can 
194b0 62 65 20 6f 6e 65 20 6f 66 3a 0a 2a 2a 0a 2a 2a  be one of:.**.**
194c0 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 51   <dl>.** <dt>[SQ
194d0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
194e0 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
194f0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
19500 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
19510 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
19520 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
19530 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
19540 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
19550 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
19560 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49  .**.** <dt>[SQLI
19570 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
19580 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
19590 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
195a0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
195b0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
195c0 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
195d0 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
195e0 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
195f0 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
19600 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
19610 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
19620 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
19630 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
19640 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
19650 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
19660 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a  returned.</dd>.*
19670 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45  *.** <dt>[SQLITE
19680 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
19690 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
196a0 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  CREATE]</dt>.** 
196b0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
196c0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
196d0 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
196e0 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74  ng, and is creat
196f0 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 64  es it if.** it d
19700 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20  oes not already 
19710 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74  exist. This is t
19720 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  he behavior that
19730 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
19740 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
19750 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
19760 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e  3_open16().</dd>
19770 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
19780 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
19790 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
197a0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
197b0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
197c0 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
197d0 6e 20 61 62 6f 76 65 20 74 68 65 6e 20 74 68 65  n above then the
197e0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
197f0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
19800 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
19810 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
19820 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
19830 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
19840 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
19850 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
19860 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69  connection.  Thi
19870 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  s in-memory data
19880 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
19890 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74   when.** the dat
198a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
198b0 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74   is closed.  Fut
198c0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
198d0 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
198e0 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69  make use of addi
198f0 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66  tional special f
19900 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65  ilenames that be
19910 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
19920 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
19930 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
19940 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74   that when a dat
19950 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61  abase filename a
19960 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67  ctually does beg
19970 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22  in with.** a ":"
19980 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73   character you s
19990 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65  hould prefix the
199a0 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61   filename with a
199b0 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61   pathname such a
199c0 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f  s.** "./" to avo
199d0 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
199e0 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e  .** If the filen
199f0 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
19a00 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
19a10 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
19a20 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
19a30 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
19a40 65 61 74 65 64 2e 20 20 54 68 69 73 20 70 72 69  eated.  This pri
19a50 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
19a60 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
19a70 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
19a80 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
19a90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19aa0 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
19ab0 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  ** The fourth pa
19ac0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
19ad0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
19ae0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
19af0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
19b00 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
19b10 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
19b20 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
19b30 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
19b40 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
19b50 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
19b60 73 65 2e 20 20 49 66 20 74 68 65 20 66 6f 75 72  se.  If the four
19b70 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
19b80 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
19b90 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
19ba0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
19bb0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
19bc0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
19bd0 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
19be0 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
19bf0 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
19c00 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
19c10 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
19c20 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
19c30 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
19c40 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
19c50 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
19c60 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
19c70 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
19c80 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
19c90 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
19ca0 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
19cb0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
19cc0 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
19cd0 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
19ce0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
19cf0 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
19d00 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
19d10 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
19d20 2a 2a 20 7b 46 31 32 37 30 31 7d 20 54 68 65 20  ** {F12701} The 
19d30 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
19d40 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
19d50 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20  6()], and.**    
19d60 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f        [sqlite3_o
19d70 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
19d80 61 63 65 73 20 63 72 65 61 74 65 20 61 20 6e 65  aces create a ne
19d90 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  w.**          [d
19da0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19db0 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  on] associated w
19dc0 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
19dd0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
19de0 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 69 72  e given in their
19df0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
19e00 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 32 7d  ..**.** {F12702}
19e10 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   The filename ar
19e20 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
19e30 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 0a 2a  reted as UTF-8.*
19e40 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 5b  *          for [
19e50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
19e60 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  and [sqlite3_ope
19e70 6e 5f 76 32 28 29 5d 20 61 6e 64 20 61 73 20 55  n_v2()] and as U
19e80 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20 20  TF-16.**        
19e90 20 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20    in the native 
19ea0 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 5b  byte order for [
19eb0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
19ec0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 33  ]..**.** {F12703
19ed0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
19ee0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
19ef0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
19f00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
19f10 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ],.**          o
19f20 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
19f30 76 32 28 29 5d 20 77 72 69 74 65 73 20 61 20 70  v2()] writes a p
19f40 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a  ointer to a new.
19f50 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
19f60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19f70 5d 20 69 6e 74 6f 20 2a 70 70 44 62 2e 0a 2a 2a  ] into *ppDb..**
19f80 0a 2a 2a 20 7b 46 31 32 37 30 34 7d 20 54 68 65  .** {F12704} The
19f90 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
19fa0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
19fb0 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20  16()], and.**   
19fc0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
19fd0 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
19fe0 66 61 63 65 73 20 72 65 74 75 72 6e 20 5b 53 51  faces return [SQ
19ff0 4c 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e 20 73 75  LITE_OK] upon su
1a000 63 63 65 73 73 2c 0a 2a 2a 20 20 20 20 20 20 20  ccess,.**       
1a010 20 20 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72     or an appropr
1a020 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
1a030 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  ] on failure..**
1a040 0a 2a 2a 20 7b 46 31 32 37 30 36 7d 20 54 68 65  .** {F12706} The
1a050 20 64 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e   default text en
1a060 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77  coding for a new
1a070 20 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65   database create
1a080 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
1a090 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65      [sqlite3_ope
1a0a0 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  n()] or [sqlite3
1a0b0 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 69 6c 6c  _open_v2()] will
1a0c0 20 62 65 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a   be UTF-8..**.**
1a0d0 20 7b 46 31 32 37 30 37 7d 20 54 68 65 20 64 65   {F12707} The de
1a0e0 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64  fault text encod
1a0f0 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61  ing for a new da
1a100 74 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75  tabase created u
1a110 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
1a120 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1a130 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ()] will be UTF-
1a140 31 36 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30  16..**.** {F1270
1a150 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
1a160 6f 70 65 6e 28 46 2c 44 29 5d 20 69 6e 74 65 72  open(F,D)] inter
1a170 66 61 63 65 20 69 73 20 65 71 75 69 76 61 6c 65  face is equivale
1a180 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  nt to.**        
1a190 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f    [sqlite3_open_
1a1a0 76 32 28 46 2c 44 2c 47 2c 30 29 5d 20 77 68 65  v2(F,D,G,0)] whe
1a1b0 72 65 20 74 68 65 20 47 20 70 61 72 61 6d 65 74  re the G paramet
1a1c0 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  er is.**        
1a1d0 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52    [SQLITE_OPEN_R
1a1e0 45 41 44 57 52 49 54 45 5d 7c 5b 53 51 4c 49 54  EADWRITE]|[SQLIT
1a1f0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 0a  E_OPEN_CREATE]..
1a200 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 31 7d 20 49  **.** {F12711} I
1a210 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65  f the G paramete
1a220 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r to [sqlite3_op
1a230 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20  en_v2(F,D,G,V)] 
1a240 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20  contains the.** 
1a250 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c           bit val
1a260 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ue [SQLITE_OPEN_
1a270 52 45 41 44 4f 4e 4c 59 5d 20 74 68 65 6e 20 74  READONLY] then t
1a280 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1a290 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  pened.**        
1a2a0 20 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e    for reading on
1a2b0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31  ly..**.** {F1271
1a2c0 32 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61  2} If the G para
1a2d0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
1a2e0 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c  3_open_v2(F,D,G,
1a2f0 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  V)] contains the
1a300 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74  .**          bit
1a310 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f   value [SQLITE_O
1a320 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 74  PEN_READWRITE] t
1a330 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
1a340 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20   is opened.**   
1a350 20 20 20 20 20 20 20 72 65 61 64 69 6e 67 20 61         reading a
1a360 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
1a370 73 73 69 62 6c 65 2c 20 6f 72 20 66 6f 72 20 72  ssible, or for r
1a380 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 20 74  eading only if t
1a390 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  he.**          f
1a3a0 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
1a3b0 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
1a3c0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 0a  erating system..
1a3d0 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 33 7d 20 49  **.** {F12713} I
1a3e0 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65  f the G paramete
1a3f0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r to [sqlite3_op
1a400 65 6e 28 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20  en(v2(F,D,G,V)] 
1a410 6f 6d 69 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  omits the.**    
1a420 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20        bit value 
1a430 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
1a440 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74  ATE] and the dat
1a450 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
1a460 2a 20 20 20 20 20 20 20 20 20 20 70 72 65 76 69  *          previ
1a470 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 61 6e 20  ously exist, an 
1a480 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1a490 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 34  d..**.** {F12714
1a4a0 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d  } If the G param
1a4b0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
1a4c0 5f 6f 70 65 6e 28 76 32 28 46 2c 44 2c 47 2c 56  _open(v2(F,D,G,V
1a4d0 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a  )] contains the.
1a4e0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20  **          bit 
1a4f0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50  value [SQLITE_OP
1a500 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 74  EN_CREATE] and t
1a510 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
1a520 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20   not.**         
1a530 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73   previously exis
1a540 74 2c 20 74 68 65 6e 20 61 6e 20 61 74 74 65 6d  t, then an attem
1a550 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 63 72  pt is made to cr
1a560 65 61 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20  eate and.**     
1a570 20 20 20 20 20 69 6e 69 74 69 61 6c 69 7a 65 20       initialize 
1a580 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a  the database..**
1a590 0a 2a 2a 20 7b 46 31 32 37 31 37 7d 20 49 66 20  .** {F12717} If 
1a5a0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
1a5b0 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
1a5c0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
1a5d0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a  te3_open16()],.*
1a5e0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
1a5f0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1a600 5d 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  ] is ":memory:",
1a610 20 74 68 65 6e 20 61 6e 20 70 72 69 76 61 74 65   then an private
1a620 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70  ,.**          ep
1a630 68 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d 65 6d 6f  hemeral, in-memo
1a640 72 79 20 64 61 74 61 62 61 73 65 20 69 73 20 63  ry database is c
1a650 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
1a660 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 20 20 20  onnection..**   
1a670 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20         <todo>Is 
1a680 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1a690 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  TE|SQLITE_OPEN_R
1a6a0 45 41 44 57 52 49 54 45 20 72 65 71 75 69 72 65  EADWRITE require
1a6b0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  d.**          in
1a6c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1a6d0 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  ()?</todo>.**.**
1a6e0 20 7b 46 31 32 37 31 39 7d 20 49 66 20 74 68 65   {F12719} If the
1a6f0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 4e 55 4c   filename is NUL
1a700 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74  L or an empty st
1a710 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
1a720 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20  vate,.**        
1a730 20 20 65 70 68 65 6d 65 72 61 6c 20 6f 6e 2d 64    ephemeral on-d
1a740 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
1a750 6c 20 62 65 20 63 72 65 61 74 65 64 2e 0a 2a 2a  l be created..**
1a760 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e            <todo>
1a770 49 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  Is SQLITE_OPEN_C
1a780 52 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45  REATE|SQLITE_OPE
1a790 4e 5f 52 45 41 44 57 52 49 54 45 20 72 65 71 75  N_READWRITE requ
1a7a0 69 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ired.**         
1a7b0 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
1a7c0 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a  _v2()?</todo>.**
1a7d0 0a 2a 2a 20 7b 46 31 32 37 32 31 7d 20 54 68 65  .** {F12721} The
1a7e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1a7f0 63 74 69 6f 6e 5d 20 63 72 65 61 74 65 64 20 62  ction] created b
1a800 79 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  y [sqlite3_open_
1a810 76 32 28 46 2c 44 2c 47 2c 56 29 5d 0a 2a 2a 20  v2(F,D,G,V)].** 
1a820 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 75 73           will us
1a830 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  e the [sqlite3_v
1a840 66 73 5d 20 6f 62 6a 65 63 74 20 69 64 65 6e 74  fs] object ident
1a850 69 66 69 65 64 20 62 79 20 74 68 65 20 56 20 70  ified by the V p
1a860 61 72 61 6d 65 74 65 72 2c 0a 2a 2a 20 20 20 20  arameter,.**    
1a870 20 20 20 20 20 20 6f 72 20 74 68 65 20 64 65 66        or the def
1a880 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
1a890 73 5d 20 6f 62 6a 65 63 74 20 69 66 20 56 20 69  s] object if V i
1a8a0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1a8b0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 32 33 7d  ..**.** {F12723}
1a8c0 20 54 77 6f 20 5b 64 61 74 61 62 61 73 65 20 63   Two [database c
1a8d0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 77 69 6c 6c  onnections] will
1a8e0 20 73 68 61 72 65 20 61 20 63 6f 6d 6d 6f 6e 20   share a common 
1a8f0 63 61 63 68 65 20 69 66 20 62 6f 74 68 20 77 65  cache if both we
1a900 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  re.**          o
1a910 70 65 6e 65 64 20 77 69 74 68 20 74 68 65 20 73  pened with the s
1a920 61 6d 65 20 56 46 53 20 77 68 69 6c 65 20 5b 73  ame VFS while [s
1a930 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
1a940 5d 20 77 61 73 20 65 6e 61 62 6c 65 64 20 61 6e  ] was enabled an
1a950 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66  d.**          if
1a960 20 62 6f 74 68 20 66 69 6c 65 6e 61 6d 65 73 20   both filenames 
1a970 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 75 73  compare equal us
1a980 69 6e 67 20 6d 65 6d 63 6d 70 28 29 20 61 66 74  ing memcmp() aft
1a990 65 72 20 68 61 76 69 6e 67 20 62 65 65 6e 0a 2a  er having been.*
1a9a0 2a 20 20 20 20 20 20 20 20 20 20 70 72 6f 63 65  *          proce
1a9b0 73 73 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ssed by the [sql
1a9c0 69 74 65 33 5f 76 66 73 20 7c 20 78 46 75 6c 6c  ite3_vfs | xFull
1a9d0 50 61 74 68 6e 61 6d 65 5d 20 6d 65 74 68 6f 64  Pathname] method
1a9e0 20 6f 66 20 74 68 65 20 56 46 53 2e 0a 2a 2f 0a   of the VFS..*/.
1a9f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
1aa00 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
1aa10 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
1aa20 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1aa30 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
1aa40 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
1aa50 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1aa60 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1aa70 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1aa80 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
1aa90 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
1aaa0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
1aab0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
1aac0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1aad0 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
1aae0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1aaf0 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
1ab00 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1ab10 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
1ab20 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
1ab30 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1ab40 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
1ab50 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
1ab60 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1ab70 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1ab80 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
1ab90 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
1aba0 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
1abb0 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
1abc0 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
1abd0 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
1abe0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
1abf0 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
1ac00 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 20 7b  s And Messages {
1ac10 46 31 32 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12800}.**.** Th
1ac20 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
1ac30 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
1ac40 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
1ac50 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
1ac60 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
1ac70 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
1ac80 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1ac90 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f   failed sqlite3_
1aca0 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73  * API call.** as
1acb0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
1acc0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1acd0 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f  tion]. If a prio
1ace0 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
1acf0 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73  d.** but the mos
1ad00 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
1ad10 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
1ad20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
1ad30 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72  om.** sqlite3_er
1ad40 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
1ad50 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ined..**.** The 
1ad60 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1ad70 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72   and sqlite3_err
1ad80 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45  msg16() return E
1ad90 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a  nglish-language.
1ada0 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73  ** text that des
1adb0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
1adc0 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  , as either UTF-
1add0 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70  8 or UTF-16 resp
1ade0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d  ectively..** Mem
1adf0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1ae00 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
1ae10 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
1ae20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54  internally..** T
1ae30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
1ae40 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
1ae50 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65  worry about free
1ae60 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a  ing the result..
1ae70 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
1ae80 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67  error string mig
1ae90 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ht be overwritte
1aea0 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
1aeb0 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e   by.** subsequen
1aec0 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72  t calls to other
1aed0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
1aee0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  e functions..**.
1aef0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1af00 2a 0a 2a 2a 20 7b 46 31 32 38 30 31 7d 20 54 68  *.** {F12801} Th
1af10 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  e [sqlite3_errco
1af20 64 65 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65  de(D)] interface
1af30 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1af40 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20  eric.**         
1af50 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
1af60 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  r [extended resu
1af70 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  lt code] for the
1af80 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 0a 2a   most recently.*
1af90 2a 20 20 20 20 20 20 20 20 20 20 66 61 69 6c 65  *          faile
1afa0 64 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c  d interface call
1afb0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1afc0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
1afd0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
1afe0 0a 2a 2a 20 7b 46 31 32 38 30 33 7d 20 54 68 65  .** {F12803} The
1aff0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1b000 28 44 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  (D)] and [sqlite
1b010 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d 0a 2a  3_errmsg16(D)].*
1b020 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
1b030 66 61 63 65 73 20 72 65 74 75 72 6e 20 45 6e 67  faces return Eng
1b040 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65  lish-language te
1b050 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
1b060 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
1b070 65 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 6d  e error in the m
1b080 6f 73 74 6c 79 20 72 65 63 65 6e 74 6c 79 20 66  ostly recently f
1b090 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20  ailed interface 
1b0a0 63 61 6c 6c 2c 0a 2a 2a 20 20 20 20 20 20 20 20  call,.**        
1b0b0 20 20 65 6e 63 6f 64 65 64 20 61 73 20 65 69 74    encoded as eit
1b0c0 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
1b0d0 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  -16 respectively
1b0e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 37 7d  ..**.** {F12807}
1b0f0 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
1b100 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1b110 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20  3_errmsg()] and 
1b120 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
1b130 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  6()].**         
1b140 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
1b150 20 74 68 65 20 6e 65 78 74 20 53 51 4c 69 74 65   the next SQLite
1b160 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2e   interface call.
1b170 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 38 7d 20  .**.** {F12808} 
1b180 43 61 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f 75  Calls to API rou
1b190 74 69 6e 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  tines that do no
1b1a0 74 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  t return an erro
1b1b0 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20  r code.**       
1b1c0 20 20 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71     (example: [sq
1b1d0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
1b1e0 28 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20  ()]) do not.**  
1b1f0 20 20 20 20 20 20 20 20 63 68 61 6e 67 65 20 74          change t
1b200 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 72  he error code or
1b210 20 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e 65   message returne
1b220 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
1b230 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1b240 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65  e()], [sqlite3_e
1b250 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71  rrmsg()], or [sq
1b260 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1b270 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 39  ]..**.** {F12809
1b280 7d 20 49 6e 74 65 72 66 61 63 65 73 20 74 68 61  } Interfaces tha
1b290 74 20 61 72 65 20 6e 6f 74 20 61 73 73 6f 63 69  t are not associ
1b2a0 61 74 65 64 20 77 69 74 68 20 61 20 73 70 65 63  ated with a spec
1b2b0 69 66 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20  ific.**         
1b2c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1b2d0 63 74 69 6f 6e 5d 20 28 65 78 61 6d 70 6c 65 73  ction] (examples
1b2e0 3a 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  :.**          [s
1b2f0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
1b300 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 6e  ] or [sqlite3_en
1b310 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
1b320 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  e()].**         
1b330 20 64 6f 20 6e 6f 74 20 63 68 61 6e 67 65 20 74   do not change t
1b340 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
1b350 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
1b360 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f    [sqlite3_errco
1b370 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  de()], [sqlite3_
1b380 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73  errmsg()], or [s
1b390 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1b3a0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
1b3b0 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
1b3c0 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63  e3 *db);.const c
1b3d0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
1b3e0 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  msg(sqlite3*);.c
1b3f0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
1b400 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
1b410 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1b420 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74  PI3REF: SQL Stat
1b430 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46 31  ement Object {F1
1b440 33 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  3000}.** KEYWORD
1b450 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
1b460 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
1b470 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
1b480 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
1b490 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
1b4a0 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
1b4b0 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
1b4c0 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
1b4d0 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e   is variously kn
1b4e0 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72  own as a "prepar
1b4f0 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  ed statement" or
1b500 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20   a.** "compiled 
1b510 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
1b520 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
1b530 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a  tatement"..**.**
1b540 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
1b550 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
1b560 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
1b570 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
1b580 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
1b590 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
1b5a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
1b5b0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
1b5c0 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
1b5d0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
1b5e0 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
1b5f0 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  o [host paramete
1b600 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
1b610 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
1b620 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
1b630 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
1b640 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
1b650 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
1b660 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
1b670 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
1b680 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  set the statemen
1b690 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1b6a0 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
1b6b0 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
1b6c0 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
1b6d0 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
1b6e0 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
1b6f0 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
1b700 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1b710 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
1b720 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66   </ol>.**.** Ref
1b730 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74  er to documentat
1b740 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
1b750 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  l methods above 
1b760 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
1b770 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
1b780 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
1b790 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
1b7a0 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
1b7b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1b7c0 2d 74 69 6d 65 20 4c 69 6d 69 74 73 20 7b 46 31  -time Limits {F1
1b7d0 32 37 36 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  2760}.**.** This
1b7e0 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
1b7f0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61  s the size of va
1b800 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73  rious constructs
1b810 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a   to be limited.*
1b820 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f  * on a connectio
1b830 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  n by connection 
1b840 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73  basis.  The firs
1b850 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
1b860 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
1b870 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73  connection] whos
1b880 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65  e limit is to be
1b890 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e   set or queried.
1b8a0 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
1b8b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65  parameter is one
1b8c0 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63   of the [limit c
1b8d0 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20  ategories] that 
1b8e0 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73  define a.** clas
1b8f0 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20  s of constructs 
1b900 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74  to be size limit
1b910 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70  ed.  The third p
1b920 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
1b930 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72  ** new limit for
1b940 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e   that construct.
1b950 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 72    The function r
1b960 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c  eturns the old l
1b970 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  imit..**.** If t
1b980 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
1b990 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
1b9a0 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
1b9b0 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f  unchanged..** Fo
1b9c0 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74 65  r the limit cate
1b9d0 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c  gory of SQLITE_L
1b9e0 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20 69  IMIT_XYZ there i
1b9f0 73 20 61 20 68 61 72 64 20 75 70 70 65 72 0a 2a  s a hard upper.*
1ba00 2a 20 62 6f 75 6e 64 20 73 65 74 20 62 79 20 61  * bound set by a
1ba10 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20   compile-time C 
1ba20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1ba30 72 6f 20 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f  ro named SQLITE_
1ba40 4d 41 58 5f 58 59 5a 2e 0a 2a 2a 20 28 54 68 65  MAX_XYZ..** (The
1ba50 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68   "_LIMIT_" in th
1ba60 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65  e name is change
1ba70 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a  d to "_MAX_".).*
1ba80 2a 20 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e  * Attempts to in
1ba90 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
1baa0 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
1bab0 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
1bac0 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
1bad0 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
1bae0 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a  upper limit..**.
1baf0 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69  ** Run time limi
1bb00 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ts are intended 
1bb10 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69  for use in appli
1bb20 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e  cations that man
1bb30 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69  age.** both thei
1bb40 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64  r own internal d
1bb50 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f  atabase and also
1bb60 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20   databases that 
1bb70 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a  are controlled.*
1bb80 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65  * by untrusted e
1bb90 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e  xternal sources.
1bba0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70    An example app
1bbb0 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62  lication might b
1bbc0 65 20 61 0a 2a 2a 20 77 65 62 62 72 6f 77 73 65  e a.** webbrowse
1bbd0 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
1bbe0 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
1bbf0 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
1bc00 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
1bc10 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
1bc20 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
1bc30 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
1bc40 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
1bc50 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
1bc60 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
1bc70 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
1bc80 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
1bc90 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
1bca0 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
1bcb0 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
1bcc0 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
1bcd0 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
1bce0 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
1bcf0 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
1bd00 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
1bd10 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
1bd20 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
1bd30 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
1bd40 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
1bd50 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1bd60 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
1bd70 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
1bd80 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
1bd90 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
1bda0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
1bdb0 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
1bdc0 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
1bdd0 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
1bde0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
1bdf0 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
1be00 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  RAGMA]..**.** Th
1be10 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
1be20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64  currently consid
1be30 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61  ered experimenta
1be40 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74  l and is subject
1be50 0a 2a 2a 20 74 6f 20 63 68 61 6e 67 65 20 6f 72  .** to change or
1be60 20 72 65 6d 6f 76 61 6c 20 77 69 74 68 6f 75 74   removal without
1be70 20 70 72 69 6f 72 20 6e 6f 74 69 63 65 2e 0a 2a   prior notice..*
1be80 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
1be90 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 36 32 7d 20  .**.** {F12762} 
1bea0 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
1beb0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69  l to [sqlite3_li
1bec0 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 72  mit(D,C,V)] wher
1bed0 65 20 56 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  e V is.**       
1bee0 20 20 20 70 6f 73 69 74 69 76 65 20 63 68 61 6e     positive chan
1bef0 67 65 73 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e  ges the limit on
1bf00 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e   the size of con
1bf10 73 74 72 75 63 74 20 43 20 69 6e 20 74 68 65 0a  struct C in the.
1bf20 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
1bf30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1bf40 5d 20 44 20 74 6f 20 74 68 65 20 6c 65 73 73 65  ] D to the lesse
1bf50 72 20 6f 66 20 56 20 61 6e 64 20 74 68 65 20 68  r of V and the h
1bf60 61 72 64 20 75 70 70 65 72 0a 2a 2a 20 20 20 20  ard upper.**    
1bf70 20 20 20 20 20 20 62 6f 75 6e 64 20 6f 6e 20 74        bound on t
1bf80 68 65 20 73 69 7a 65 20 6f 66 20 43 20 74 68 61  he size of C tha
1bf90 74 20 69 73 20 73 65 74 20 61 74 20 63 6f 6d 70  t is set at comp
1bfa0 69 6c 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ile-time..**.** 
1bfb0 7b 46 31 32 37 36 36 7d 20 41 20 73 75 63 63 65  {F12766} A succe
1bfc0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
1bfd0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43  qlite3_limit(D,C
1bfe0 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69 73 20  ,V)] where V is 
1bff0 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20  negative.**     
1c000 20 20 20 20 20 6c 65 61 76 65 73 20 74 68 65 20       leaves the 
1c010 73 74 61 74 65 20 6f 66 20 74 68 65 20 5b 64 61  state of the [da
1c020 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c030 6e 5d 20 44 20 75 6e 63 68 61 6e 67 65 64 2e 0a  n] D unchanged..
1c040 2a 2a 0a 2a 2a 20 7b 46 31 32 37 36 39 7d 20 41  **.** {F12769} A
1c050 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
1c060 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   to [sqlite3_lim
1c070 69 74 28 44 2c 43 2c 56 29 5d 20 72 65 74 75 72  it(D,C,V)] retur
1c080 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
1c090 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20     value of the 
1c0a0 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a  limit on the siz
1c0b0 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43  e of construct C
1c0c0 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   in the.**      
1c0d0 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
1c0e0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 61 73 20 69  nnection] D as i
1c0f0 74 20 77 61 73 20 70 72 69 6f 72 20 74 6f 20 74  t was prior to t
1c100 68 65 20 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20  he call..*/.int 
1c110 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
1c120 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
1c130 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
1c140 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
1c150 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
1c160 65 67 6f 72 69 65 73 20 7b 46 31 32 37 39 30 7d  egories {F12790}
1c170 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
1c180 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
1c190 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
1c1a0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
1c1b0 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
1c1c0 61 72 69 6f 75 73 20 61 73 70 65 63 74 73 20 6f  arious aspects o
1c1d0 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  f a [database co
1c1e0 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61  nnection].** tha
1c1f0 74 20 63 61 6e 20 62 65 20 6c 69 6d 69 74 65 64  t can be limited
1c200 20 69 6e 20 73 69 7a 65 20 62 79 20 63 61 6c 6c   in size by call
1c210 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69  s to [sqlite3_li
1c220 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 6d  mit()]..** The m
1c230 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
1c240 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 61 72  arious limits ar
1c250 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  e as follows:.**
1c260 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
1c270 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
1c280 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
1c290 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
1c2a0 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
1c2b0 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
1c2c0 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  row.<dd>.**.** <
1c2d0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1c2e0 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
1c2f0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1c300 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
1c310 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  SQL statement.</
1c320 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
1c330 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
1c340 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
1c350 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1c360 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
1c370 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
1c380 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
1c390 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 53  esult set of a S
1c3a0 45 4c 45 43 54 20 6f 72 20 74 68 65 20 6d 61 78  ELECT or the max
1c3b0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
1c3c0 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
1c3d0 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
1c3e0 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
1c3f0 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
1c400 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1c410 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
1c420 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1c430 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
1c440 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
1c450 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
1c460 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  sion.</dd>.**.**
1c470 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1c480 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
1c490 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
1c4a0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1c4b0 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63   of terms in a c
1c4c0 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73  ompound SELECT s
1c4d0 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a  tatement.</dd>.*
1c4e0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1c4f0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
1c500 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1c510 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1c520 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
1c530 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
1c540 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
1c550 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
1c560 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
1c570 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1c580 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
1c590 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
1c5a0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1c5b0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
1c5c0 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
1c5d0 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
1c5e0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1c5f0 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
1c600 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1c610 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 74 74 61  m number of atta
1c620 63 68 65 64 20 64 61 74 61 62 61 73 65 73 2e 3c  ched databases.<
1c630 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1c640 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
1c650 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c  _PATTERN_LENGTH<
1c660 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1c670 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
1c680 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72  f the pattern ar
1c690 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 4c 49  gument to the LI
1c6a0 4b 45 20 6f 72 0a 2a 2a 20 47 4c 4f 42 20 6f 70  KE or.** GLOB op
1c6b0 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a  erators.</dd>.**
1c6c0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
1c6d0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1c6e0 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
1c6f0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1c700 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73  ber of variables
1c710 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
1c720 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a  ment that can.**
1c730 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a   be bound.</dd>.
1c740 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
1c750 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1c760 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
1c770 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
1c780 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1c790 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
1c7a0 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
1c7b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1c7c0 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
1c7d0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
1c7e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1c7f0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
1c800 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
1c810 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1c820 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
1c830 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
1c840 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c850 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
1c860 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c870 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
1c880 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
1c890 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
1c8a0 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
1c8b0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
1c8c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c8d0 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
1c8e0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
1c8f0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
1c900 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
1c910 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
1c920 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
1c930 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      9../*.** CAP
1c940 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
1c950 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
1c960 74 20 7b 46 31 33 30 31 30 7d 0a 2a 2a 20 4b 45  t {F13010}.** KE
1c970 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
1c980 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
1c990 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
1c9a0 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
1c9b0 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
1c9c0 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
1c9d0 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
1c9e0 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
1c9f0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
1ca00 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
1ca10 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
1ca20 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
1ca30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
1ca40 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
1ca50 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b   prior call to [
1ca60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
1ca70 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1ca80 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
1ca90 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _open16()]..**.*
1caa0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
1cab0 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
1cac0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
1cad0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
1cae0 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
1caf0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
1cb00 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
1cb10 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
1cb20 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1cb30 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
1cb40 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
1cb50 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
1cb60 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
1cb70 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1cb80 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
1cb90 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74  {END}.**.** If t
1cba0 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
1cbb0 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  t is less than z
1cbc0 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
1cbd0 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
1cbe0 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
1cbf0 65 72 6d 69 6e 61 74 6f 72 2e 20 49 66 20 6e 42  erminator. If nB
1cc00 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
1cc10 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
1cc20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e  the maximum.** n
1cc30 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20  umber of  bytes 
1cc40 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
1cc50 20 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e   When nByte is n
1cc60 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
1cc70 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20  .** zSql string 
1cc80 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74  ends at either t
1cc90 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20  he first '\000' 
1cca0 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72  or '\u0000' char
1ccb0 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20  acter or.** the 
1ccc0 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77  nByte-th byte, w
1ccd0 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
1cce0 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c  irst. If the cal
1ccf0 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61  ler knows.** tha
1cd00 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
1cd10 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
1cd20 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68  minated, then th
1cd30 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a  ere is a small.*
1cd40 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  * performance ad
1cd50 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61  vantage to be ga
1cd60 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ined by passing 
1cd70 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
1cd80 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71  er that.** is eq
1cd90 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65  ual to the numbe
1cda0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
1cdb0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
1cdc0 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
1cdd0 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
1cde0 6e 61 74 6f 72 20 62 79 74 65 73 2e 7b 45 4e 44  nator bytes.{END
1cdf0 7d 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20  }.**.** *pzTail 
1ce00 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
1ce10 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
1ce20 74 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  te past the end 
1ce30 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
1ce40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1ce50 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
1ce60 75 74 69 6e 65 73 20 6f 6e 6c 79 20 63 6f 6d 70  utines only comp
1ce70 69 6c 65 20 74 68 65 20 66 69 72 73 74 0a 2a 2a  ile the first.**
1ce80 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
1ce90 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
1cea0 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
1ceb0 74 6f 20 77 68 61 74 20 72 65 6d 61 69 6e 73 0a  to what remains.
1cec0 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ** uncompiled..*
1ced0 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 20  *.** *ppStmt is 
1cee0 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
1cef0 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
1cf00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1cf10 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
1cf20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
1cf30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1cf40 20 20 49 66 20 74 68 65 72 65 20 69 73 20 61 6e    If there is an
1cf50 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
1cf60 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
1cf70 4c 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75 74  L.  If the input
1cf80 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e   text contains n
1cf90 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e  o SQL (if the in
1cfa0 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a  put is an empty.
1cfb0 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ** string or a c
1cfc0 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
1cfd0 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
1cfe0 55 4c 4c 2e 0a 2a 2a 20 7b 55 31 33 30 31 38 7d  ULL..** {U13018}
1cff0 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
1d000 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
1d010 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
1d020 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
1d030 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1d040 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1d050 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
1d060 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
1d070 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a  d with it..**.**
1d080 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51   On success, [SQ
1d090 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
1d0a0 72 6e 65 64 2c 20 6f 74 68 65 72 77 69 73 65 20  rned, otherwise 
1d0b0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
1d0c0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
1d0d0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
1d0e0 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
1d0f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1d100 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
1d110 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
1d120 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
1d130 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
1d140 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
1d150 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
1d160 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
1d170 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
1d180 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
1d190 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
1d1a0 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e  * In the "v2" in
1d1b0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
1d1c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1d1d0 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
1d1e0 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
1d1f0 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
1d200 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
1d210 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
1d220 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 7b 45  nal SQL text. {E
1d230 4e 44 7d 20 54 68 69 73 20 63 61 75 73 65 73 20  ND} This causes 
1d240 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
1d250 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
1d260 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69  o.** behave a di
1d270 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f  fferently in two
1d280 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
1d290 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20  >.** <li>.** If 
1d2a0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
1d2b0 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
1d2c0 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
1d2d0 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
1d2e0 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
1d2f0 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
1d300 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
1d310 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
1d320 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
1d330 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
1d340 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
1d350 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68  it again.  If th
1d360 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61  e schema has cha
1d370 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79  nged in.** a way
1d380 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20   that makes the 
1d390 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e  statement no lon
1d3a0 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69  ger valid, [sqli
1d3b0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
1d3c0 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e   still.** return
1d3d0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1d3e0 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68  .  But unlike th
1d3f0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
1d400 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  r, [SQLITE_SCHEM
1d410 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66  A] is.** now a f
1d420 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c  atal error.  Cal
1d430 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  ling [sqlite3_pr
1d440 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69  epare_v2()] agai
1d450 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20  n will not make 
1d460 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20  the.** error go 
1d470 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65  away.  Note: use
1d480 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1d490 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ()] to find the 
1d4a0 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70  text.** of the p
1d4b0 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61  arsing error tha
1d4c0 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20  t results in an 
1d4d0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
1d4e0 72 65 74 75 72 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a  return. {END}.**
1d4f0 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
1d500 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72 72  >.** When an err
1d510 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69  or occurs, [sqli
1d520 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
1d530 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74   return one of t
1d540 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b  he detailed.** [
1d550 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20  error codes] or 
1d560 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
1d570 63 6f 64 65 73 5d 2e 20 20 54 68 65 20 6c 65 67  codes].  The leg
1d580 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73  acy behavior was
1d590 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65   that.** [sqlite
1d5a0 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20  3_step()] would 
1d5b0 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65  only return a ge
1d5c0 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52  neric [SQLITE_ER
1d5d0 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65  ROR] result code
1d5e0 0a 2a 2a 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c  .** and you woul
1d5f0 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
1d600 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20   second call to 
1d610 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1d620 5d 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  ] in order.** to
1d630 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
1d640 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
1d650 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20  e problem. With 
1d660 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
1d670 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20  .** interfaces, 
1d680 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72  the underlying r
1d690 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72  eason for the er
1d6a0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
1d6b0 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
1d6c0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  </li>.** </ol>.*
1d6d0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
1d6e0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 31 7d 20  .**.** {F13011} 
1d6f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  The [sqlite3_pre
1d700 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e  pare(db,zSql,...
1d710 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  )] and.**       
1d720 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
1d730 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e  are_v2(db,zSql,.
1d740 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  ..)] interfaces 
1d750 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a  interpret the.**
1d760 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20 69            text i
1d770 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72  n their zSql par
1d780 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d 38 2e  ameter as UTF-8.
1d790 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 32 7d 20  .**.** {F13012} 
1d7a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  The [sqlite3_pre
1d7b0 70 61 72 65 31 36 28 64 62 2c 7a 53 71 6c 2c 2e  pare16(db,zSql,.
1d7c0 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ..)] and.**     
1d7d0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72       [sqlite3_pr
1d7e0 65 70 61 72 65 31 36 5f 76 32 28 64 62 2c 7a 53  epare16_v2(db,zS
1d7f0 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  ql,...)] interfa
1d800 63 65 73 20 69 6e 74 65 72 70 72 65 74 20 74 68  ces interpret th
1d810 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65  e.**          te
1d820 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71 6c  xt in their zSql
1d830 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 55 54   parameter as UT
1d840 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
1d850 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
1d860 2a 0a 2a 2a 20 7b 46 31 33 30 31 33 7d 20 49 66  *.** {F13013} If
1d870 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
1d880 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
1d890 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53  prepare_v2(db,zS
1d8a0 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a  ql,nByte,...)].*
1d8b0 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 69  *          and i
1d8c0 74 73 20 76 61 72 69 61 6e 74 73 20 69 73 20 6c  ts variants is l
1d8d0 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74  ess than zero, t
1d8e0 68 65 20 53 51 4c 20 74 65 78 74 20 69 73 0a 2a  he SQL text is.*
1d8f0 2a 20 20 20 20 20 20 20 20 20 20 72 65 61 64 20  *          read 
1d900 66 72 6f 6d 20 7a 53 71 6c 20 69 73 20 72 65 61  from zSql is rea
1d910 64 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  d up to the firs
1d920 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
1d930 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 34  r..**.** {F13014
1d940 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61  } If the nByte a
1d950 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
1d960 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64  te3_prepare_v2(d
1d970 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e  b,zSql,nByte,...
1d980 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  )].**          a
1d990 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  nd its variants 
1d9a0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
1d9b0 20 74 68 65 6e 20 61 74 20 6d 6f 73 74 20 6e 42   then at most nB
1d9c0 79 74 65 73 20 62 79 74 65 73 20 6f 66 0a 2a 2a  ytes bytes of.**
1d9d0 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 74 65            SQL te
1d9e0 78 74 20 69 73 20 72 65 61 64 20 66 72 6f 6d 20  xt is read from 
1d9f0 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  zSql..**.** {F13
1da00 30 31 35 7d 20 49 6e 20 5b 73 71 6c 69 74 65 33  015} In [sqlite3
1da10 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a  _prepare_v2(db,z
1da20 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61 69 6c 29 5d  Sql,N,P,pzTail)]
1da30 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
1da40 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66  s.**          if
1da50 20 74 68 65 20 7a 53 71 6c 20 69 6e 70 75 74 20   the zSql input 
1da60 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6d 6f  text contains mo
1da70 72 65 20 74 68 61 6e 20 6f 6e 65 20 53 51 4c 20  re than one SQL 
1da80 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20  statement.**    
1da90 20 20 20 20 20 20 61 6e 64 20 70 7a 54 61 69 6c        and pzTail
1daa0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
1dab0 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
1dac0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
1dad0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  he.**          f
1dae0 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20 74  irst byte past t
1daf0 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69  he end of the fi
1db00 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
1db10 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a 2a 20 20 20  t in zSql..**   
1db20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 57 68 61         <todo>Wha
1db30 74 20 64 6f 65 73 20 2a 70 7a 54 61 69 6c 20 70  t does *pzTail p
1db40 6f 69 6e 74 20 74 6f 20 69 66 20 74 68 65 72 65  oint to if there
1db50 20 69 73 20 6f 6e 65 20 73 74 61 74 65 6d 65 6e   is one statemen
1db60 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20  t?</todo>.**.** 
1db70 7b 46 31 33 30 31 36 7d 20 41 20 73 75 63 63 65  {F13016} A succe
1db80 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
1db90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1dba0 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 70 70 53 74  2(db,zSql,N,ppSt
1dbb0 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  mt,...)].**     
1dbc0 20 20 20 20 20 6f 72 20 6f 6e 65 20 6f 66 20 69       or one of i
1dbd0 74 73 20 76 61 72 69 61 6e 74 73 20 77 72 69 74  ts variants writ
1dbe0 65 73 20 69 6e 74 6f 20 2a 70 70 53 74 6d 74 20  es into *ppStmt 
1dbf0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
1dc00 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ew.**          [
1dc10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1dc20 6e 74 5d 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  nt] or a pointer
1dc30 20 74 6f 20 4e 55 4c 4c 20 69 66 20 7a 53 71 6c   to NULL if zSql
1dc40 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20   contains.**    
1dc50 20 20 20 20 20 20 6e 6f 74 68 69 6e 67 20 6f 74        nothing ot
1dc60 68 65 72 20 74 68 61 6e 20 77 68 69 74 65 73 70  her than whitesp
1dc70 61 63 65 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 2e  ace or comments.
1dc80 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 39 7d 20  .**.** {F13019} 
1dc90 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  The [sqlite3_pre
1dca0 70 61 72 65 5f 76 32 28 29 5d 20 69 6e 74 65 72  pare_v2()] inter
1dcb0 66 61 63 65 20 61 6e 64 20 69 74 73 20 76 61 72  face and its var
1dcc0 69 61 6e 74 73 20 72 65 74 75 72 6e 0a 2a 2a 20  iants return.** 
1dcd0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
1dce0 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61 70 70 72 6f  _OK] or an appro
1dcf0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
1dd00 64 65 5d 20 75 70 6f 6e 20 66 61 69 6c 75 72 65  de] upon failure
1dd10 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 32 31 7d  ..**.** {F13021}
1dd20 20 42 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33   Before [sqlite3
1dd30 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71 6c  _prepare(db,zSql
1dd40 2c 6e 42 79 74 65 2c 70 70 53 74 6d 74 2c 70 7a  ,nByte,ppStmt,pz
1dd50 54 61 69 6c 29 5d 20 6f 72 20 69 74 73 0a 2a 2a  Tail)] or its.**
1dd60 20 20 20 20 20 20 20 20 20 20 76 61 72 69 61 6e            varian
1dd70 74 73 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  ts returns an er
1dd80 72 6f 72 20 28 61 6e 79 20 76 61 6c 75 65 20 6f  ror (any value o
1dd90 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1dda0 45 5f 4f 4b 5d 29 2c 0a 2a 2a 20 20 20 20 20 20  E_OK]),.**      
1ddb0 20 20 20 20 74 68 65 79 20 66 69 72 73 74 20 73      they first s
1ddc0 65 74 20 2a 70 70 53 74 6d 74 20 74 6f 20 4e 55  et *ppStmt to NU
1ddd0 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  LL..*/.int sqlit
1dde0 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
1ddf0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1de00 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1de10 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1de20 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
1de30 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1de40 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
1de50 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1de60 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1de70 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1de80 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1de90 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1dea0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1deb0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1dec0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1ded0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
1dee0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1def0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1df00 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1df10 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
1df20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1df30 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1df40 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1df50 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1df60 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1df70 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1df80 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1df90 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
1dfa0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1dfb0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1dfc0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1dfd0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1dfe0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1dff0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1e000 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1e010 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1e020 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
1e030 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1e040 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1e050 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1e060 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1e070 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
1e080 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1e090 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1e0a0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1e0b0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
1e0c0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1e0d0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
1e0e0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1e0f0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1e100 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1e110 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1e120 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1e130 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1e140 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1e150 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1e160 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
1e170 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1e180 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1e190 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1e1a0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1e1b0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
1e1c0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1e1d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1e1e0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1e1f0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
1e200 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1e210 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1e220 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
1e230 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
1e240 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
1e250 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
1e260 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
1e270 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
1e280 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
1e290 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
1e2a0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1e2b0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
1e2c0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
1e2d0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
1e2e0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
1e2f0 2f 2a 0a 2a 2a 20 43 41 50 49 52 45 46 3a 20 52  /*.** CAPIREF: R
1e300 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
1e310 65 6e 74 20 53 51 4c 20 7b 46 31 33 31 30 30 7d  ent SQL {F13100}
1e320 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1e330 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
1e340 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20  d to retrieve a 
1e350 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68  saved copy of th
1e360 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51  e original.** SQ
1e370 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63  L text used to c
1e380 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65  reate a [prepare
1e390 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20  d statement] if 
1e3a0 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77  that statement w
1e3b0 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75  as.** compiled u
1e3c0 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
1e3d0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1e3e0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
1e3f0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
1e400 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
1e410 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 31 7d  :.**.** {F13101}
1e420 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   If the [prepare
1e430 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73  d statement] pas
1e440 73 65 64 20 61 73 20 74 68 65 20 61 72 67 75 6d  sed as the argum
1e450 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ent to.**       
1e460 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28     [sqlite3_sql(
1e470 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  )] was compiled 
1e480 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
1e490 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1e4a0 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ()] or.**       
1e4b0 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
1e4c0 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 74 68 65  are16_v2()], the
1e4d0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29  n [sqlite3_sql()
1e4e0 5d 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  ] returns.**    
1e4f0 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65 72 20        a pointer 
1e500 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
1e510 61 74 65 64 20 73 74 72 69 6e 67 20 63 6f 6e 74  ated string cont
1e520 61 69 6e 69 6e 67 20 61 20 55 54 46 2d 38 20 72  aining a UTF-8 r
1e530 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20 20  endering.**     
1e540 20 20 20 20 20 6f 66 20 74 68 65 20 6f 72 69 67       of the orig
1e550 69 6e 61 6c 20 53 51 4c 20 73 74 61 74 65 6d 65  inal SQL stateme
1e560 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30  nt..**.** {F1310
1e570 32 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61  2} If the [prepa
1e580 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70  red statement] p
1e590 61 73 73 65 64 20 61 73 20 74 68 65 20 61 72 67  assed as the arg
1e5a0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20  ument to.**     
1e5b0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 71       [sqlite3_sq
1e5c0 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65  l()] was compile
1e5d0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
1e5e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1e5f0 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
1e600 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61    [sqlite3_prepa
1e610 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 5b 73  re16()], then [s
1e620 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 72 65  qlite3_sql()] re
1e630 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1e640 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  nter..**.** {F13
1e650 31 30 33 7d 20 54 68 65 20 73 74 72 69 6e 67 20  103} The string 
1e660 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1e670 69 74 65 33 5f 73 71 6c 28 53 29 5d 20 69 73 20  ite3_sql(S)] is 
1e680 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 0a  valid until the.
1e690 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
1e6a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1e6b0 20 53 20 69 73 20 64 65 6c 65 74 65 64 20 75 73   S is deleted us
1e6c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
1e6d0 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f  alize(S)]..*/.co
1e6e0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1e6f0 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  3_sql(sqlite3_st
1e700 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
1e710 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
1e720 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
1e730 61 6c 75 65 20 4f 62 6a 65 63 74 20 7b 46 31 35  alue Object {F15
1e740 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  000}.** KEYWORDS
1e750 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
1e760 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
1e770 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1e780 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
1e790 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
1e7a0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1e7b0 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
1e7c0 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
1e7d0 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
1e7e0 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
1e7f0 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
1e800 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
1e810 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
1e820 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 56 61  es it stores. Va
1e830 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
1e840 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1e850 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69  ects.** can be i
1e860 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
1e870 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
1e880 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
1e890 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41  or NULL..**.** A
1e8a0 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
1e8b0 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69  object may be ei
1e8c0 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22  ther "protected"
1e8d0 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64   or "unprotected
1e8e0 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72  "..** Some inter
1e8f0 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20  faces require a 
1e900 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1e910 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20  3_value.  Other 
1e920 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69  interfaces.** wi
1e930 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72  ll accept either
1e940 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20   a protected or 
1e950 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
1e960 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
1e970 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65   Every interface
1e980 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71   that accepts sq
1e990 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75  lite3_value argu
1e9a0 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a  ments specifies.
1e9b0 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
1e9c0 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
1e9d0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1e9e0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  3_value..**.** T
1e9f0 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63  he terms "protec
1ea00 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74  ted" and "unprot
1ea10 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20  ected" refer to 
1ea20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a  whether or not.*
1ea30 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c  * a mutex is hel
1ea40 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d  d.  A internal m
1ea50 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
1ea60 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   a protected.** 
1ea70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1ea80 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65  ject but no mute
1ea90 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e  x is held for an
1eaa0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
1eab0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1eac0 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65  ject.  If SQLite
1ead0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   is compiled to 
1eae0 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  be single-thread
1eaf0 65 64 0a 2a 2a 20 28 77 69 74 68 20 53 51 4c 49  ed.** (with SQLI
1eb00 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 20  TE_THREADSAFE=0 
1eb10 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
1eb20 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
1eb30 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
1eb40 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
1eb50 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
1eb60 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
1eb70 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
1eb80 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
1eb90 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
1eba0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
1ebb0 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
1ebc0 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
1ebd0 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
1ebe0 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
1ebf0 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
1ec00 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
1ec10 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
1ec20 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
1ec30 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
1ec40 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
1ec50 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
1ec60 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65  alue objects eve
1ec70 6e 20 69 66 20 74 68 65 79 20 61 72 65 20 73 69  n if they are si
1ec80 6e 67 6c 65 20 74 68 72 65 61 64 65 64 2e 0a 2a  ngle threaded..*
1ec90 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1eca0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74  _value objects t
1ecb0 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61  hat are passed a
1ecc0 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74  s parameters int
1ecd0 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  o the.** impleme
1ece0 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c  ntation of [appl
1ecf0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
1ed00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61  SQL functions] a
1ed10 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a  re protected..**
1ed20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
1ed30 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ue object return
1ed40 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
1ed50 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
1ed60 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64  ] is unprotected
1ed70 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64  ..** Unprotected
1ed80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1ed90 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20  bjects may only 
1eda0 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20  be used with.** 
1edb0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
1edc0 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
1edd0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
1ede0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ()]..** The [sql
1edf0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20  ite3_value_blob 
1ee00 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  | sqlite3_value_
1ee10 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f  type()] family o
1ee20 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  f.** interfaces 
1ee30 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65  require protecte
1ee40 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
1ee50 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65  objects..*/.type
1ee60 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73  def struct Mem s
1ee70 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f  qlite3_value;../
1ee80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1ee90 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
1eea0 65 78 74 20 4f 62 6a 65 63 74 20 7b 46 31 36 30  ext Object {F160
1eeb0 30 31 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  01}.**.** The co
1eec0 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
1eed0 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
1eee0 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
1eef0 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
1ef00 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
1ef10 74 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  t.  A pointer to
1ef20 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74   an sqlite3_cont
1ef30 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73  ext object.** is
1ef40 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61   always first pa
1ef50 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c  rameter to [appl
1ef60 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
1ef70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  SQL functions]..
1ef80 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1ef90 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
1efa0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
1efb0 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73  tation will pass
1efc0 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72   this.** pointer
1efd0 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61   through into ca
1efe0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1eff0 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c  result_int | sql
1f000 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a  ite3_result()],.
1f010 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  ** [sqlite3_aggr
1f020 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d  egate_context()]
1f030 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  , [sqlite3_user_
1f040 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  data()],.** [sql
1f050 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
1f060 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69  handle()], [sqli
1f070 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
1f080 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73  )],.** and/or [s
1f090 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
1f0a0 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  ta()]..*/.typede
1f0b0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
1f0c0 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33  _context sqlite3
1f0d0 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a  _context;../*.**
1f0e0 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69   CAPI3REF: Bindi
1f0f0 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
1f100 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
1f110 20 7b 46 31 33 35 30 30 7d 0a 2a 2a 20 4b 45 59   {F13500}.** KEY
1f120 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72  WORDS: {host par
1f130 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61  ameter} {host pa
1f140 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20  rameters} {host 
1f150 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a  parameter name}.
1f160 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
1f170 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51  L parameter} {SQ
1f180 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70  L parameters} {p
1f190 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
1f1a0 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53  }.**.** In the S
1f1b0 51 4c 20 73 74 72 69 6e 67 73 20 69 6e 70 75 74  QL strings input
1f1c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
1f1d0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69  pare_v2()] and i
1f1e0 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20  ts variants,.** 
1f1f0 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20  literals may be 
1f200 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 70 61  replaced by a pa
1f210 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65 20 6f  rameter in one o
1f220 66 20 74 68 65 73 65 20 66 6f 72 6d 73 3a 0a 2a  f these forms:.*
1f230 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
1f240 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
1f250 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
1f260 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
1f270 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
1f280 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
1f290 68 65 20 70 61 72 61 6d 65 74 65 72 20 66 6f 72  he parameter for
1f2a0 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 4e  ms shown above N
1f2b0 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  NN is an integer
1f2c0 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64   literal,.** and
1f2d0 20 56 56 56 20 69 73 20 61 6e 20 61 6c 70 68 61   VVV is an alpha
1f2e0 2d 6e 75 6d 65 72 69 63 20 70 61 72 61 6d 65 74  -numeric paramet
1f2f0 65 72 20 6e 61 6d 65 2e 20 54 68 65 20 76 61 6c  er name. The val
1f300 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
1f310 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
1f320 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
1f330 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
1f340 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
1f350 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
1f360 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
1f370 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1f380 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
1f390 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  re..**.** The fi
1f3a0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
1f3b0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1f3c0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73  _*() routines is
1f3d0 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69   always.** a poi
1f3e0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
1f3f0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
1f400 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
1f410 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1f420 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
1f430 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a   variants..**.**
1f440 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
1f450 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
1f460 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
1f470 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
1f480 2e 0a 2a 2a 20 54 68 65 20 6c 65 66 74 6d 6f 73  ..** The leftmos
1f490 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
1f4a0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
1f4b0 31 2e 20 20 57 68 65 6e 20 74 68 65 20 73 61 6d  1.  When the sam
1f4c0 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
1f4d0 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
1f4e0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
1f4f0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
1f500 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
1f510 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
1f520 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
1f530 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
1f540 65 2e 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78 20  e..** The index 
1f550 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
1f560 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
1f570 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
1f580 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1f590 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
1f5a0 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
1f5b0 64 2e 20 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a  d.  The index.**
1f5c0 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
1f5d0 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
1f5e0 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54  lue of NNN..** T
1f5f0 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
1f600 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
1f610 6e 64 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  nd the compile-t
1f620 69 6d 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ime.** parameter
1f630 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49   SQLITE_MAX_VARI
1f640 41 42 4c 45 5f 4e 55 4d 42 45 52 20 28 64 65 66  ABLE_NUMBER (def
1f650 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29  ault value: 999)
1f660 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72  ..**.** The thir
1f670 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
1f680 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
1f690 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
1f6a0 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65  ..**.** In those
1f6b0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
1f6c0 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
1f6d0 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
1f6e0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
1f6f0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
1f700 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
1f710 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
1f720 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
1f730 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
1f740 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
1f750 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
1f760 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
1f770 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72  ..** If the four
1f780 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
1f790 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65  negative, the le
1f7a0 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
1f7b0 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  ng is.** the num
1f7c0 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
1f7d0 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
1f7e0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
1f7f0 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61 72  .** The fifth ar
1f800 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
1f810 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73  3_bind_blob(), s
1f820 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1f830 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  (), and.** sqlit
1f840 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
1f850 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
1f860 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
1f870 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
1f880 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20  ** string after 
1f890 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73  SQLite has finis
1f8a0 68 65 64 20 77 69 74 68 20 69 74 2e 20 49 66 20  hed with it. If 
1f8b0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
1f8c0 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
1f8d0 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
1f8e0 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
1f8f0 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
1f900 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
1f910 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
1f920 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
1f930 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
1f940 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
1f950 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  eed..** If the f
1f960 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
1f970 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
1f980 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
1f990 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  then.** SQLite m
1f9a0 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69  akes its own pri
1f9b0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
1f9c0 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
1f9d0 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  y, before.** the
1f9e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
1f9f0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
1fa00 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
1fa10 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
1fa20 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
1fa30 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
1fa40 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73  gth N that.** is
1fa50 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
1fa60 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62  oes.  A zeroblob
1fa70 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
1fa80 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
1fa90 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
1faa0 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
1fab0 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
1fac0 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
1fad0 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
1fae0 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
1faf0 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
1fb00 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
1fb10 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
1fb20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
1fb30 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
1fb40 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
1fb50 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
1fb60 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
1fb70 2a 20 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c  * A negative val
1fb80 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
1fb90 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
1fba0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
1fbb0 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  B..**.** The sql
1fbc0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1fbd0 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
1fbe0 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b  alled after.** [
1fbf0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1fc00 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76  v2()] (and its v
1fc10 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c  ariants) or [sql
1fc20 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e  ite3_reset()] an
1fc30 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c  d.** before [sql
1fc40 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1fc50 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f   Bindings are no
1fc60 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
1fc70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1fc80 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55  )] routine..** U
1fc90 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
1fca0 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
1fcb0 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
1fcc0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1fcd0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1fce0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
1fcf0 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69   an error code i
1fd00 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f  f.** anything go
1fd10 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49  es wrong.  [SQLI
1fd20 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
1fd30 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
1fd40 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
1fd50 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
1fd60 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d    [SQLITE_NOMEM]
1fd70 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
1fd80 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
1fd90 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
1fda0 45 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  E] might be retu
1fdb0 72 6e 65 64 20 69 66 20 74 68 65 73 65 20 72 6f  rned if these ro
1fdc0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
1fdd0 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61  d on a.** virtua
1fde0 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69  l machine that i
1fdf0 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74  s the wrong stat
1fe00 65 20 6f 72 20 77 68 69 63 68 20 68 61 73 20 61  e or which has a
1fe10 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61  lready been fina
1fe20 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74  lized..** Detect
1fe30 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 73  ion of misuse is
1fe40 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 70   unreliable.  Ap
1fe50 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
1fe60 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20  d not depend.** 
1fe70 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  on SQLITE_MISUSE
1fe80 20 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 54   returns.  SQLIT
1fe90 45 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74 65  E_MISUSE is inte
1fea0 6e 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  nded to indicate
1feb0 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72   a.** a logic er
1fec0 72 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c 69  ror in the appli
1fed0 63 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 20  cation.  Future 
1fee0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1fef0 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69  te might.** pani
1ff00 63 20 72 61 74 68 65 72 20 74 68 61 6e 20 72 65  c rather than re
1ff10 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
1ff20 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  SE..**.** See al
1ff30 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
1ff40 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
1ff50 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
1ff60 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1ff70 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _name()], and [s
1ff80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1ff90 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
1ffa0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
1ffb0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 30 36 7d  :.**.** {F13506}
1ffc0 20 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65 6d   The [SQL statem
1ffd0 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 72 65  ent compiler] re
1ffe0 63 6f 67 6e 69 7a 65 73 20 74 6f 6b 65 6e 73 20  cognizes tokens 
1fff0 6f 66 20 74 68 65 20 66 6f 72 6d 73 0a 2a 2a 20  of the forms.** 
20000 20 20 20 20 20 20 20 20 20 22 3f 22 2c 20 22 3f           "?", "?
20010 4e 4e 4e 22 2c 20 22 24 56 56 56 22 2c 20 22 3a  NNN", "$VVV", ":
20020 56 56 56 22 2c 20 61 6e 64 20 22 40 56 56 56 22  VVV", and "@VVV"
20030 20 61 73 20 53 51 4c 20 70 61 72 61 6d 65 74 65   as SQL paramete
20040 72 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rs,.**          
20050 77 68 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e 79  where NNN is any
20060 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65   sequence of one
20070 20 6f 72 20 6d 6f 72 65 20 64 69 67 69 74 73 0a   or more digits.
20080 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  **          and 
20090 77 68 65 72 65 20 56 56 56 20 69 73 20 61 6e 79  where VVV is any
200a0 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65   sequence of one
200b0 20 6f 72 20 6d 6f 72 65 20 61 6c 70 68 61 6e 75   or more alphanu
200c0 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20  meric.**        
200d0 20 20 63 68 61 72 61 63 74 65 72 73 20 6f 72 20    characters or 
200e0 22 3a 3a 22 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  "::" optionally 
200f0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 20 73 74  followed by a st
20100 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 0a  ring containing.
20110 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 20 73  **          no s
20120 70 61 63 65 73 20 61 6e 64 20 63 6f 6e 74 61 69  paces and contai
20130 6e 65 64 20 77 69 74 68 69 6e 20 70 61 72 65 6e  ned within paren
20140 74 68 65 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  theses..**.** {F
20150 31 33 35 30 39 7d 20 54 68 65 20 69 6e 69 74 69  13509} The initi
20160 61 6c 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53  al value of an S
20170 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
20180 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  NULL..**.** {F13
20190 35 31 32 7d 20 54 68 65 20 69 6e 64 65 78 20 6f  512} The index o
201a0 66 20 61 6e 20 22 3f 22 20 53 51 4c 20 70 61 72  f an "?" SQL par
201b0 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6c 61  ameter is one la
201c0 72 67 65 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a  rger than the.**
201d0 20 20 20 20 20 20 20 20 20 20 6c 61 72 67 65 73            larges
201e0 74 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70  t index of SQL p
201f0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
20200 6c 65 66 74 2c 20 6f 72 20 31 20 69 66 0a 2a 2a  left, or 1 if.**
20210 20 20 20 20 20 20 20 20 20 20 74 68 65 20 22 3f            the "?
20220 22 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73  " is the leftmos
20230 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 2e  t SQL parameter.
20240 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31 35 7d 20  .**.** {F13515} 
20250 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  The index of an 
20260 22 3f 4e 4e 4e 22 20 53 51 4c 20 70 61 72 61 6d  "?NNN" SQL param
20270 65 74 65 72 20 69 73 20 74 68 65 20 69 6e 74 65  eter is the inte
20280 67 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b  ger NNN..**.** {
20290 46 31 33 35 31 38 7d 20 54 68 65 20 69 6e 64 65  F13518} The inde
202a0 78 20 6f 66 20 61 6e 20 22 3a 56 56 56 22 2c 20  x of an ":VVV", 
202b0 22 24 56 56 56 22 2c 20 6f 72 20 22 40 56 56 56  "$VVV", or "@VVV
202c0 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  " SQL parameter 
202d0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  is.**          t
202e0 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 69  he same as the i
202f0 6e 64 65 78 20 6f 66 20 6c 65 66 74 6d 6f 73 74  ndex of leftmost
20300 20 6f 63 63 75 72 72 65 6e 63 65 73 20 6f 66 20   occurrences of 
20310 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20  the same.**     
20320 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2c 20       parameter, 
20330 6f 72 20 6f 6e 65 20 6d 6f 72 65 20 74 68 61 6e  or one more than
20340 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64   the largest ind
20350 65 78 20 6f 76 65 72 20 61 6c 6c 0a 2a 2a 20 20  ex over all.**  
20360 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65          paramete
20370 72 73 20 74 6f 20 74 68 65 20 6c 65 66 74 20 69  rs to the left i
20380 66 20 74 68 69 73 20 69 73 20 74 68 65 20 66 69  f this is the fi
20390 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 0a 2a  rst occurrence.*
203a0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
203b0 69 73 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72  is parameter, or
203c0 20 31 20 69 66 20 74 68 69 73 20 69 73 20 74 68   1 if this is th
203d0 65 20 6c 65 66 74 6d 6f 73 74 20 70 61 72 61 6d  e leftmost param
203e0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  eter..**.** {F13
203f0 35 32 31 7d 20 54 68 65 20 5b 53 51 4c 20 73 74  521} The [SQL st
20400 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
20410 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20  ] fails with an 
20420 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 0a 2a  [SQLITE_RANGE].*
20430 2a 20 20 20 20 20 20 20 20 20 20 65 72 72 6f 72  *          error
20440 20 69 66 20 74 68 65 20 69 6e 64 65 78 20 6f 66   if the index of
20450 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
20460 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31  r is less than 1
20470 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
20480 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65  greater than the
20490 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 53 51   compile-time SQ
204a0 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c  LITE_MAX_VARIABL
204b0 45 5f 4e 55 4d 42 45 52 0a 2a 2a 20 20 20 20 20  E_NUMBER.**     
204c0 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2e 0a       parameter..
204d0 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 34 7d 20 43  **.** {F13524} C
204e0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
204f0 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c  _bind_text | sql
20500 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c  ite3_bind(S,N,V,
20510 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
20520 20 20 61 73 73 6f 63 69 61 74 65 20 74 68 65 20    associate the 
20530 76 61 6c 75 65 20 56 20 77 69 74 68 20 61 6c 6c  value V with all
20540 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
20550 68 61 76 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20  having an.**    
20560 20 20 20 20 20 20 69 6e 64 65 78 20 6f 66 20 4e        index of N
20570 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
20580 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
20590 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 37 7d 20 43  **.** {F13527} C
205a0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
205b0 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c  _bind_text | sql
205c0 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e  ite3_bind(S,N,..
205d0 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
205e0 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72 20 63  override prior c
205f0 61 6c 6c 73 20 77 69 74 68 20 74 68 65 20 73 61  alls with the sa
20600 6d 65 20 76 61 6c 75 65 73 20 6f 66 20 53 20 61  me values of S a
20610 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  nd N..**.** {F13
20620 35 33 30 7d 20 42 69 6e 64 69 6e 67 73 20 65 73  530} Bindings es
20630 74 61 62 6c 69 73 68 65 64 20 62 79 20 5b 73 71  tablished by [sq
20640 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
20650 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53  | sqlite3_bind(S
20660 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
20670 20 20 20 70 65 72 73 69 73 74 20 61 63 72 6f 73     persist acros
20680 73 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  s calls to [sqli
20690 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a  te3_reset(S)]..*
206a0 2a 0a 2a 2a 20 7b 46 31 33 35 33 33 7d 20 49 6e  *.** {F13533} In
206b0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
206c0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e  e3_bind_blob(S,N
206d0 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,L,D)],.**    
206e0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
206f0 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c  ind_text(S,N,V,L
20700 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
20710 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
20720 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c  nd_text16(S,N,V,
20730 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e  L,D)] SQLite bin
20740 64 73 20 74 68 65 20 66 69 72 73 74 20 4c 0a 2a  ds the first L.*
20750 2a 20 20 20 20 20 20 20 20 20 20 62 79 74 65 73  *          bytes
20760 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20   of the BLOB or 
20770 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74  string pointed t
20780 6f 20 62 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a  o by V, when L.*
20790 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f  *          is no
207a0 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  n-negative..**.*
207b0 2a 20 7b 46 31 33 35 33 36 7d 20 49 6e 20 63 61  * {F13536} In ca
207c0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
207d0 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c  bind_text(S,N,V,
207e0 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  L,D)] or.**     
207f0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
20800 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c  nd_text16(S,N,V,
20810 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e  L,D)] SQLite bin
20820 64 73 20 63 68 61 72 61 63 74 65 72 73 0a 2a 2a  ds characters.**
20830 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 56            from V
20840 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
20850 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
20860 72 20 77 68 65 6e 20 4c 20 69 73 20 6e 65 67 61  r when L is nega
20870 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  tive..**.** {F13
20880 35 33 39 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  539} In calls to
20890 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
208a0 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c  lob(S,N,V,L,D)],
208b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
208c0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
208d0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a  S,N,V,L,D)], or.
208e0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
208f0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
20900 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65  (S,N,V,L,D)] whe
20910 6e 20 44 20 69 73 20 74 68 65 20 73 70 65 63 69  n D is the speci
20920 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  al.**          c
20930 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f  onstant [SQLITE_
20940 53 54 41 54 49 43 5d 2c 20 53 51 4c 69 74 65 20  STATIC], SQLite 
20950 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
20960 20 76 61 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20   value V.**     
20970 20 20 20 20 20 69 73 20 68 65 6c 64 20 69 6e 20       is held in 
20980 73 74 61 74 69 63 20 75 6e 6d 61 6e 61 67 65 64  static unmanaged
20990 20 73 70 61 63 65 20 74 68 61 74 20 77 69 6c 6c   space that will
209a0 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20   not change.**  
209b0 20 20 20 20 20 20 20 20 64 75 72 69 6e 67 20 74          during t
209c0 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74  he lifetime of t
209d0 68 65 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a  he binding..**.*
209e0 2a 20 7b 46 31 33 35 34 32 7d 20 49 6e 20 63 61  * {F13542} In ca
209f0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
20a00 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  bind_blob(S,N,V,
20a10 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  L,D)],.**       
20a20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
20a30 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
20a40 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
20a50 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
20a60 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
20a70 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 65  )] when D is the
20a80 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20   special.**     
20a90 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53       constant [S
20aa0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
20ab0 2c 20 74 68 65 20 72 6f 75 74 69 6e 65 20 6d 61  , the routine ma
20ac0 6b 65 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20  kes a.**        
20ad0 20 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f    private copy o
20ae0 66 20 74 68 65 20 76 61 6c 75 65 20 56 20 62 65  f the value V be
20af0 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
20b00 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 35 7d 20  .**.** {F13545} 
20b10 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  In calls to [sql
20b20 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53  ite3_bind_blob(S
20b30 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20  ,N,V,L,D)],.**  
20b40 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
20b50 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56  _bind_text(S,N,V
20b60 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  ,L,D)], or.**   
20b70 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
20b80 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c  bind_text16(S,N,
20b90 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69  V,L,D)] when D i
20ba0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  s a pointer to.*
20bb0 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 75 6e  *          a fun
20bc0 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69 6e  ction, SQLite in
20bd0 76 6f 6b 65 73 20 74 68 61 74 20 66 75 6e 63 74  vokes that funct
20be0 69 6f 6e 20 74 6f 20 64 65 73 74 72 6f 79 20 74  ion to destroy t
20bf0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  he.**          v
20c00 61 6c 75 65 20 56 20 61 66 74 65 72 20 69 74 20  alue V after it 
20c10 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
20c20 6e 67 20 74 68 65 20 76 61 6c 75 65 20 56 2e 0a  ng the value V..
20c30 2a 2a 0a 2a 2a 20 7b 46 31 33 35 34 38 7d 20 49  **.** {F13548} I
20c40 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
20c50 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
20c60 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 20  b(S,N,V,L)] the 
20c70 76 61 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 20  value bound.**  
20c80 20 20 20 20 20 20 20 20 69 73 20 61 20 42 4c 4f          is a BLO
20c90 42 20 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f 72  B of L bytes, or
20ca0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
20cb0 4c 4f 42 20 69 66 20 4c 20 69 73 20 6e 65 67 61  LOB if L is nega
20cc0 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  tive..**.** {F13
20cd0 35 35 31 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  551} In calls to
20ce0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
20cf0 61 6c 75 65 28 53 2c 4e 2c 56 29 5d 20 74 68 65  alue(S,N,V)] the
20d00 20 56 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 0a   V argument may.
20d10 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 20 65  **          be e
20d20 69 74 68 65 72 20 61 20 5b 70 72 6f 74 65 63 74  ither a [protect
20d30 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
20d40 5d 20 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a 2a  ] object or an.*
20d50 2a 20 20 20 20 20 20 20 20 20 20 5b 75 6e 70 72  *          [unpr
20d60 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
20d70 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  value] object..*
20d80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
20d90 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
20da0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
20db0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
20dc0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
20dd0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
20de0 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  d_double(sqlite3
20df0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75  _stmt*, int, dou
20e00 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ble);.int sqlite
20e10 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
20e20 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
20e30 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
20e40 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
20e50 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
20e60 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
20e70 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
20e80 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
20e90 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  mt*, int);.int s
20ea0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
20eb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
20ec0 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  int, const char*
20ed0 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
20ee0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
20ef0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
20f00 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
20f10 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
20f20 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
20f30 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
20f40 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
20f50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
20f60 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
20f70 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
20f80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
20f90 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
20fa0 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b  t*, int, int n);
20fb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20fc0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20  : Number Of SQL 
20fd0 50 61 72 61 6d 65 74 65 72 73 20 7b 46 31 33 36  Parameters {F136
20fe0 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00}.**.** This r
20ff0 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
21000 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
21010 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61  umber of [SQL pa
21020 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20  rameters].** in 
21030 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
21040 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72  ement].  SQL par
21050 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65  ameters are toke
21060 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ns of the.** for
21070 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22  m "?", "?NNN", "
21080 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f  :AAA", "$AAA", o
21090 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65  r "@AAA" that se
210a0 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68  rve as.** placeh
210b0 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65  olders for value
210c0 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69  s that are [sqli
210d0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
210e0 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65  bound].** to the
210f0 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61   parameters at a
21100 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a   later time..**.
21110 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
21120 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
21130 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
21140 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
21150 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
21160 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
21170 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
21180 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
21190 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
211a0 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
211b0 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
211c0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
211d0 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c 0a   ?NNN are used,.
211e0 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20  ** there may be 
211f0 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
21200 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
21210 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
21220 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
21230 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
21240 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
21250 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
21260 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
21270 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
21280 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
21290 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36  NTS:.**.** {F136
212a0 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
212b0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
212c0 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72 66  count(S)] interf
212d0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ace returns.**  
212e0 20 20 20 20 20 20 20 20 74 68 65 20 6c 61 72 67          the larg
212f0 65 73 74 20 69 6e 64 65 78 20 6f 66 20 61 6c 6c  est index of all
21300 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
21310 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
21320 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
21330 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30 20  tement] S, or 0 
21340 69 66 20 53 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  if S contains no
21350 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2e   SQL parameters.
21360 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
21370 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
21380 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
21390 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
213a0 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20  3REF: Name Of A 
213b0 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20 7b  Host Parameter {
213c0 46 31 33 36 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F13620}.**.** Th
213d0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
213e0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
213f0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
21400 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20 70 61 72  n-th.** [SQL par
21410 61 6d 65 74 65 72 5d 20 69 6e 20 61 20 5b 70 72  ameter] in a [pr
21420 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21430 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65  ]..** SQL parame
21440 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
21450 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
21460 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
21470 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20  $AAA".** have a 
21480 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68  name which is th
21490 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20  e string "?NNN" 
214a0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
214b0 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
214c0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
214d0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
214e0 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
214f0 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20  " or "$" or "@" 
21500 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63  or "?".** is inc
21510 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
21520 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61   the name..** Pa
21530 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
21540 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74  form "?" without
21550 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74   a following int
21560 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d  eger have no nam
21570 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 61 6c 73  e.** and are als
21580 6f 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  o referred to as
21590 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61   "anonymous para
215a0 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54  meters"..**.** T
215b0 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61  he first host pa
215c0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
215d0 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30  ndex of 1, not 0
215e0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76  ..**.** If the v
215f0 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f 66  alue n is out of
21600 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
21610 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   n-th parameter 
21620 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
21630 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
21640 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74 75  urned.  The retu
21650 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a  rned string is.*
21660 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d  * always in UTF-
21670 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20  8 encoding even 
21680 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72  if the named par
21690 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72  ameter was.** or
216a0 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
216b0 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
216c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
216d0 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  16()] or.** [sql
216e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
216f0 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
21700 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
21710 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
21720 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
21730 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
21740 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
21750 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
21760 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
21770 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  dex()]..**.** IN
21780 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
21790 7b 46 31 33 36 32 31 7d 20 54 68 65 20 5b 73 71  {F13621} The [sq
217a0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
217b0 65 74 65 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20  eter_name(S,N)] 
217c0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
217d0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  s.**          a 
217e0 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
217f0 6f 66 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  of the name of t
21800 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
21810 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   in.**          
21820 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
21830 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 76 69 6e  atement] S havin
21840 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a 2a  g index N, or.**
21850 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 69            NULL i
21860 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 53 51  f there is no SQ
21870 4c 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68  L parameter with
21880 20 69 6e 64 65 78 20 4e 20 6f 72 20 69 66 20 74   index N or if t
21890 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  he.**          p
218a0 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e  arameter with in
218b0 64 65 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f 6e  dex N is an anon
218c0 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 20  ymous parameter 
218d0 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  "?"..*/.const ch
218e0 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64  ar *sqlite3_bind
218f0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
21900 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
21910 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
21920 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41  3REF: Index Of A
21930 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20   Parameter With 
21940 41 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 46 31  A Given Name {F1
21950 33 36 34 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75  3640}.**.** Retu
21960 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  rn the index of 
21970 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
21980 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
21990 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76    The.** index v
219a0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
219b0 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73   suitable for us
219c0 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  e as the second.
219d0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
219e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
219f0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
21a00 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69  )].  A zero.** i
21a10 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f  s returned if no
21a20 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65   matching parame
21a30 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 54  ter is found.  T
21a40 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
21a50 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
21a60 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
21a70 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
21a80 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
21a90 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
21aa0 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
21ab0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
21ac0 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
21ad0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
21ae0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
21af0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
21b00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
21b10 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
21b20 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
21b30 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
21b40 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a  ter_index()]..**
21b50 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
21b60 2a 2a 0a 2a 2a 20 7b 46 31 33 36 34 31 7d 20 54  **.** {F13641} T
21b70 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
21b80 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
21b90 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
21ba0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
21bb0 20 20 20 20 20 74 68 65 20 69 6e 64 65 78 20 6f       the index o
21bc0 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  f SQL parameter 
21bd0 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
21be0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20   statement].**  
21bf0 20 20 20 20 20 20 20 20 53 20 77 68 6f 73 65 20          S whose 
21c00 6e 61 6d 65 20 6d 61 74 63 68 65 73 20 74 68 65  name matches the
21c10 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 4e 2c   UTF-8 string N,
21c20 20 6f 72 20 30 20 69 66 20 74 68 65 72 65 20 69   or 0 if there i
21c30 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f  s.**          no
21c40 20 6d 61 74 63 68 2e 0a 2a 2f 0a 69 6e 74 20 73   match..*/.int s
21c50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
21c60 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
21c70 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
21c80 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
21c90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21ca0 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
21cb0 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
21cc0 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 36   Statement {F136
21cd0 36 30 7d 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61  60}.**.** Contra
21ce0 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
21cf0 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
21d00 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
21d10 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
21d20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
21d30 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
21d40 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
21d50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
21d60 2a 20 55 73 65 20 74 68 69 73 20 72 6f 75 74 69  * Use this routi
21d70 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
21d80 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
21d90 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49  to NULL..**.** I
21da0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
21db0 20 7b 46 31 33 36 36 31 7d 20 54 68 65 20 5b 73   {F13661} The [s
21dc0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
21dd0 64 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 72 66  dings(S)] interf
21de0 61 63 65 20 72 65 73 65 74 73 20 61 6c 6c 20 53  ace resets all S
21df0 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  QL.**          p
21e00 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
21e10 73 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  s in the [prepar
21e20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
21e30 62 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  back to NULL..*/
21e40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65  .int sqlite3_cle
21e50 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
21e60 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
21e70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
21e80 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
21e90 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b  n A Result Set {
21ea0 46 31 33 37 31 30 7d 0a 2a 2a 0a 2a 2a 20 52 65  F13710}.**.** Re
21eb0 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
21ec0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
21ed0 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
21ee0 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
21ef0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
21f00 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69  ent]. This routi
21f10 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
21f20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
21f30 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
21f40 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
21f50 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
21f60 70 6c 65 20 61 6e 20 55 50 44 41 54 45 29 2e 0a  ple an UPDATE)..
21f70 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
21f80 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 31 31 7d  :.**.** {F13711}
21f90 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
21fa0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69  lumn_count(S)] i
21fb0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
21fc0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
21fd0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d  *          colum
21fe0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
21ff0 20 73 65 74 20 67 65 6e 65 72 61 74 65 64 20 62   set generated b
22000 79 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  y the [prepared 
22010 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a  statement] S,.**
22020 20 20 20 20 20 20 20 20 20 20 6f 72 20 30 20 69            or 0 i
22030 66 20 53 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e  f S does not gen
22040 65 72 61 74 65 20 61 20 72 65 73 75 6c 74 20 73  erate a result s
22050 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  et..*/.int sqlit
22060 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
22070 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
22080 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
22090 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
220a0 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
220b0 53 65 74 20 7b 46 31 33 37 32 30 7d 0a 2a 2a 0a  Set {F13720}.**.
220c0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
220d0 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
220e0 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
220f0 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
22100 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
22110 6c 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45  lt set of a SELE
22120 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54  CT statement.  T
22130 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
22140 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
22150 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
22160 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
22170 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
22180 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
22190 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
221a0 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
221b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
221c0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
221d0 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
221e0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
221f0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
22200 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22210 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
22220 6d 65 6e 74 73 20 74 68 65 20 53 45 4c 45 43 54  ments the SELECT
22230 20 73 74 61 74 65 6d 65 6e 74 2e 20 54 68 65 20   statement. The 
22240 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
22250 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   is the.** colum
22260 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c  n number.  The l
22270 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
22280 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
22290 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
222a0 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
222b0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
222c0 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  her the [prepare
222d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
222e0 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
222f0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
22300 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
22310 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
22320 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
22330 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
22340 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
22350 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
22360 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  olumn..**.** If 
22370 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
22380 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
22390 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
223a0 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
223b0 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
223c0 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
223d0 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
223e0 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
223f0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
22400 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
22410 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** The name of a
22420 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
22430 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
22440 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
22450 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
22460 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
22470 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
22480 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
22490 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
224a0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
224b0 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
224c0 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
224d0 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
224e0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
224f0 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
22500 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
22510 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 31 7d 20  .**.** {F13721} 
22520 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76  A successful inv
22530 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  ocation of the [
22540 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
22550 61 6d 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20  ame(S,N)].**    
22560 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20        interface 
22570 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65  returns the name
22580 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   of the Nth colu
22590 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73 0a 2a  mn (where 0 is.*
225a0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6c  *          the l
225b0 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20  eftmost column) 
225c0 66 6f 72 20 74 68 65 20 72 65 73 75 6c 74 20 73  for the result s
225d0 65 74 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  et of the.**    
225e0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
225f0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 73 20  statement] S as 
22600 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
22610 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  d UTF-8 string..
22620 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 33 7d 20 41  **.** {F13723} A
22630 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
22640 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73  cation of the [s
22650 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
22660 6d 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20  me16(S,N)].**   
22670 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
22680 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61 6d   returns the nam
22690 65 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  e of the Nth col
226a0 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73 0a  umn (where 0 is.
226b0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
226c0 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29  leftmost column)
226d0 20 66 6f 72 20 74 68 65 20 72 65 73 75 6c 74 20   for the result 
226e0 73 65 74 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  set of the.**   
226f0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
22700 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 73   statement] S as
22710 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
22720 65 64 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ed UTF-16 string
22730 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
22740 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
22750 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  order..**.** {F1
22760 33 37 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  3724} The [sqlit
22770 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
22780 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
22790 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 5d 0a  olumn_name16()].
227a0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
227b0 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 61 20  rfaces return a 
227c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
227d0 74 68 65 79 20 61 72 65 20 75 6e 61 62 6c 65 20  they are unable 
227e0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  to.**          a
227f0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
22800 6f 20 68 6f 6c 64 20 74 68 65 69 72 20 6e 6f 72  o hold their nor
22810 6d 61 6c 20 72 65 74 75 72 6e 20 73 74 72 69 6e  mal return strin
22820 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32  gs..**.** {F1372
22830 35 7d 20 49 66 20 74 68 65 20 4e 20 70 61 72 61  5} If the N para
22840 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
22850 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c  3_column_name(S,
22860 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  N)] or.**       
22870 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
22880 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  mn_name16(S,N)] 
22890 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
228a0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20   then the.**    
228b0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
228c0 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70   return a NULL p
228d0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ointer..**.** {F
228e0 31 33 37 32 36 7d 20 54 68 65 20 73 74 72 69 6e  13726} The strin
228f0 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  gs returned by [
22900 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
22910 61 6d 65 28 53 2c 4e 29 5d 20 61 6e 64 0a 2a 2a  ame(S,N)] and.**
22920 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
22930 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
22940 28 53 2c 4e 29 5d 20 61 72 65 20 76 61 6c 69 64  (S,N)] are valid
22950 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a   until the next.
22960 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
22970 20 74 6f 20 65 69 74 68 65 72 20 72 6f 75 74 69   to either routi
22980 6e 65 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ne with the same
22990 20 53 20 61 6e 64 20 4e 20 70 61 72 61 6d 65 74   S and N paramet
229a0 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ers.**          
229b0 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
229c0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69  3_finalize(S)] i
229d0 73 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  s called..**.** 
229e0 7b 46 31 33 37 32 37 7d 20 57 68 65 6e 20 61 20  {F13727} When a 
229f0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
22a00 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
22a10 65 6d 65 6e 74 20 63 6f 6e 74 61 69 6e 73 0a 2a  ement contains.*
22a20 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 41 53  *          an AS
22a30 20 63 6c 61 75 73 65 2c 20 74 68 65 20 6e 61 6d   clause, the nam
22a40 65 20 6f 66 20 74 68 61 74 20 63 6f 6c 75 6d 6e  e of that column
22a50 20 69 73 20 74 68 65 20 69 64 65 6e 74 69 66 69   is the identifi
22a60 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
22a70 6f 20 74 68 65 20 72 69 67 68 74 20 6f 66 20 74  o the right of t
22a80 68 65 20 41 53 20 6b 65 79 77 6f 72 64 2e 0a 2a  he AS keyword..*
22a90 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
22aa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
22ab0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
22ac0 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76   int N);.const v
22ad0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
22ae0 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
22af0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
22b00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22b10 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74  F: Source Of Dat
22b20 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73  a In A Query Res
22b30 75 6c 74 20 7b 46 31 33 37 34 30 7d 0a 2a 2a 0a  ult {F13740}.**.
22b40 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
22b50 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
22b60 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 77  s to determine w
22b70 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68  hat column of wh
22b80 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77  at.** table in w
22b90 68 69 63 68 20 64 61 74 61 62 61 73 65 20 61 20  hich database a 
22ba0 72 65 73 75 6c 74 20 6f 66 20 61 20 53 45 4c 45  result of a SELE
22bb0 43 54 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  CT statement com
22bc0 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20  es from..** The 
22bd0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
22be0 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
22bf0 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
22c00 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
22c10 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20  ther a UTF-8 or 
22c20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
22c30 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
22c40 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
22c50 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
22c60 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
22c70 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
22c80 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
22c90 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
22ca0 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
22cb0 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
22cc0 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75  ame..** The retu
22cd0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
22ce0 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
22cf0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22d00 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
22d10 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
22d20 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
22d30 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65  r until the same
22d40 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
22d50 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61  requested.** aga
22d60 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e  in in a differen
22d70 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  t encoding..**.*
22d80 2a 20 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75  * The names retu
22d90 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69  rned are the ori
22da0 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64  ginal un-aliased
22db0 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a   names of the.**
22dc0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
22dd0 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a  , and column..**
22de0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
22df0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f  gument to the fo
22e00 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73  llowing calls is
22e10 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
22e20 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73  tement]..** Thes
22e30 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
22e40 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
22e50 62 6f 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c  bout the Nth col
22e60 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a  umn returned by.
22e70 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
22e80 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
22e90 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
22ea0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
22eb0 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   If the Nth colu
22ec0 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  mn returned by t
22ed0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
22ee0 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  an expression or
22ef0 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64  .** subquery and
22f00 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e   is not a column
22f10 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c   value, then all
22f20 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
22f30 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55  ons return.** NU
22f40 4c 4c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  LL.  These routi
22f50 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
22f60 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
22f70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
22f80 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
22f90 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68  .  Otherwise, th
22fa0 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  ey return the na
22fb0 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
22fc0 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
22fd0 6c 65 0a 2a 2a 20 61 6e 64 20 63 6f 6c 75 6d 6e  le.** and column
22fe0 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
22ff0 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  lt column was ex
23000 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
23010 0a 2a 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20  .** As with all 
23020 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49  other SQLite API
23030 73 2c 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78  s, those postfix
23040 65 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  ed with "16" ret
23050 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
23060 63 6f 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74  coded strings, t
23070 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f  he other functio
23080 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e  ns return UTF-8.
23090 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
230a0 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
230b0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
230c0 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
230d0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
230e0 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  ** SQLITE_ENABLE
230f0 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
23100 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79   preprocessor sy
23110 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  mbol defined..**
23120 0a 2a 2a 20 7b 55 31 33 37 35 31 7d 0a 2a 2a 20  .** {U13751}.** 
23130 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
23140 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
23150 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
23160 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
23170 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
23180 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23190 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
231a0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
231b0 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
231c0 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
231d0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
231e0 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34 31 7d  :.**.** {F13741}
231f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
23200 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
23210 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  me(S,N)] interfa
23220 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
23230 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
23240 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  e UTF-8 zero-ter
23250 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20  minated name of 
23260 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f  the database fro
23270 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20  m which the.**  
23280 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75          Nth resu
23290 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  lt column of the
232a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
232b0 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61  ment] S is extra
232c0 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20  cted,.**        
232d0 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65    or NULL if the
232e0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53   Nth column of S
232f0 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78   is a general ex
23300 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20  pression.**     
23310 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c       or if unabl
23320 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
23330 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68  mory to store th
23340 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  e name..**.** {F
23350 31 33 37 34 32 7d 20 54 68 65 20 5b 73 71 6c 69  13742} The [sqli
23360 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
23370 61 73 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  ase_name16(S,N)]
23380 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
23390 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
233a0 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36        the UTF-16
233b0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
233c0 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  er zero-terminat
233d0 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  ed name of the d
233e0 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20 20  atabase.**      
233f0 20 20 20 20 66 72 6f 6d 20 77 68 69 63 68 20 74      from which t
23400 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
23410 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65  lumn of the [pre
23420 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23430 20 53 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20   S is.**        
23440 20 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20    extracted, or 
23450 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20  NULL if the Nth 
23460 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61  column of S is a
23470 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73   general express
23480 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
23490 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20  or if unable to 
234a0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
234b0 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d  to store the nam
234c0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34 33  e..**.** {F13743
234d0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
234e0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
234f0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
23500 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
23510 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
23520 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
23530 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68  nated name of th
23540 65 20 74 61 62 6c 65 20 66 72 6f 6d 20 77 68 69  e table from whi
23550 63 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ch the.**       
23560 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f     Nth result co
23570 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65  lumn of the [pre
23580 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23590 20 53 20 69 73 20 65 78 74 72 61 63 74 65 64 2c   S is extracted,
235a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
235b0 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20  NULL if the Nth 
235c0 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61  column of S is a
235d0 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73   general express
235e0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
235f0 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20  or if unable to 
23600 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
23610 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d  to store the nam
23620 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34 34  e..**.** {F13744
23630 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
23640 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
23650 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
23660 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
23670 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
23680 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  e UTF-16 native 
23690 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d  byte order zero-
236a0 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20  terminated name 
236b0 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20  of the table.** 
236c0 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 77 68           from wh
236d0 69 63 68 20 74 68 65 20 4e 74 68 20 72 65 73 75  ich the Nth resu
236e0 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  lt column of the
236f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23700 6d 65 6e 74 5d 20 53 20 69 73 0a 2a 2a 20 20 20  ment] S is.**   
23710 20 20 20 20 20 20 20 65 78 74 72 61 63 74 65 64         extracted
23720 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  , or NULL if the
23730 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53   Nth column of S
23740 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78   is a general ex
23750 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20  pression.**     
23760 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c       or if unabl
23770 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
23780 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68  mory to store th
23790 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  e name..**.** {F
237a0 31 33 37 34 35 7d 20 54 68 65 20 5b 73 71 6c 69  13745} The [sqli
237b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
237c0 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74  n_name(S,N)] int
237d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
237e0 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
237f0 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f    the UTF-8 zero
23800 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65  -terminated name
23810 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
23820 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68 20  lumn from which 
23830 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
23840 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
23850 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72  n of the [prepar
23860 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
23870 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a  is extracted,.**
23880 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c            or NUL
23890 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  L if the Nth col
238a0 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65  umn of S is a ge
238b0 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
238c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
238d0 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  if unable to all
238e0 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
238f0 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
23900 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34 36 7d 20 54  **.** {F13746} T
23910 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
23920 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
23930 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
23940 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
23950 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
23960 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
23970 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65  te order zero-te
23980 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66  rminated name of
23990 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 20 20   the table.**   
239a0 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20 66 72         column fr
239b0 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e 74 68  om which the Nth
239c0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f   result column o
239d0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
239e0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
239f0 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72  ement] S is extr
23a00 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69  acted, or NULL i
23a10 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
23a20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
23a30 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65  S is a general e
23a40 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20  xpression or if 
23a50 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
23a60 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20  te memory.**    
23a70 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74        to store t
23a80 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b  he name..**.** {
23a90 46 31 33 37 34 38 7d 20 54 68 65 20 72 65 74 75  F13748} The retu
23aa0 72 6e 20 76 61 6c 75 65 73 20 66 72 6f 6d 0a 2a  rn values from.*
23ab0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
23ac0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
23ad0 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d  ase_name | colum
23ae0 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
23af0 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20  faces].**       
23b00 20 20 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72     are valid for
23b10 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
23b20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
23b30 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20  tatement].**    
23b40 20 20 20 20 20 20 6f 72 20 75 6e 74 69 6c 20 74        or until t
23b50 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 63  he encoding is c
23b60 68 61 6e 67 65 64 20 62 79 20 61 6e 6f 74 68 65  hanged by anothe
23b70 72 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20 20  r metadata.**   
23b80 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
23b90 20 63 61 6c 6c 20 66 6f 72 20 74 68 65 20 73 61   call for the sa
23ba0 6d 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  me prepared stat
23bb0 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
23bc0 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49  ..**.** LIMITATI
23bd0 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 33 37  ONS:.**.** {U137
23be0 35 31 7d 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  51} If two or mo
23bf0 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
23c00 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20  one or more.**  
23c10 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
23c20 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
23c30 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d  _name | column m
23c40 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63  etadata interfac
23c50 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  es].**          
23c60 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72  for the same [pr
23c70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23c80 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c  ] and result col
23c90 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  umn.**          
23ca0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
23cb0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
23cc0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
23cd0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
23ce0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
23cf0 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
23d00 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
23d10 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
23d20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
23d30 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
23d40 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
23d50 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
23d60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
23d70 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
23d80 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
23d90 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
23da0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
23db0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
23dc0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
23dd0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
23de0 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
23df0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
23e00 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
23e10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
23e20 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
23e30 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
23e40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
23e50 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
23e60 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
23e70 6c 74 20 7b 46 31 33 37 36 30 7d 0a 2a 2a 0a 2a  lt {F13760}.**.*
23e80 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
23e90 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
23ea0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
23eb0 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
23ec0 65 6d 65 6e 74 20 69 73 20 61 20 53 45 4c 45 43  ement is a SELEC
23ed0 54 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  T statement and 
23ee0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
23ef0 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
23f00 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
23f10 74 68 61 74 20 53 45 4c 45 43 54 20 69 73 20 61  that SELECT is a
23f20 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
23f30 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
23f40 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
23f50 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
23f60 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
23f70 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
23f80 73 20 72 65 74 75 72 6e 65 64 2e 20 20 49 66 20  s returned.  If 
23f90 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
23fa0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
23fb0 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
23fc0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
23fd0 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
23fe0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
23ff0 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  d..** The return
24000 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
24010 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
24020 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 46  d. {END}.**.** F
24030 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
24040 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
24050 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
24060 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
24070 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
24080 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
24090 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
240a0 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
240b0 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
240c0 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
240d0 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
240e0 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
240f0 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
24100 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
24110 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
24120 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
24130 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
24140 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
24150 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
24160 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
24170 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
24180 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20  ime typing.  So 
24190 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
241a0 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
241b0 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
241c0 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
241d0 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
241e0 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
241f0 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
24200 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
24210 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
24220 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
24230 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
24240 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
24250 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
24260 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20  ic.  Type.** is 
24270 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
24280 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65  individual value
24290 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20  s, not with the 
242a0 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73  containers.** us
242b0 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65  ed to hold those
242c0 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49   values..**.** I
242d0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
242e0 20 7b 46 31 33 37 36 31 7d 20 20 41 20 73 75 63   {F13761}  A suc
242f0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
24300 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
24310 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20 72  decltype(S,N)] r
24320 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20  eturns a.**     
24330 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
24340 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
24350 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
24360 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 74  e declared datat
24370 79 70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ype.**          
24380 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
24390 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72  lumn that appear
243a0 73 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c  s as the Nth col
243b0 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 0a 2a 2a  umn (numbered.**
243c0 20 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20             from 
243d0 30 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  0) of the result
243e0 20 73 65 74 20 74 6f 20 74 68 65 20 5b 70 72 65   set to the [pre
243f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24400 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 36   S..**.** {F1376
24410 32 7d 20 20 41 20 73 75 63 63 65 73 73 66 75 6c  2}  A successful
24420 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
24430 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
24440 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20  e16(S,N)].**    
24450 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61         returns a
24460 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
24470 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
24480 79 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e 67  yte order string
24490 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f  .**           co
244a0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63  ntaining the dec
244b0 6c 61 72 65 64 20 64 61 74 61 74 79 70 65 20 6f  lared datatype o
244c0 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
244d0 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72 73 0a  mn that appears.
244e0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 73 20  **           as 
244f0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28  the Nth column (
24500 6e 75 6d 62 65 72 65 64 20 66 72 6f 6d 20 30 29  numbered from 0)
24510 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
24520 65 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  et to the.**    
24530 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
24540 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
24550 2a 0a 2a 2a 20 7b 46 31 33 37 36 33 7d 20 20 49  *.** {F13763}  I
24560 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
24570 20 30 20 6f 72 20 4e 20 69 73 20 67 72 65 61 74   0 or N is great
24580 65 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  er than or equal
24590 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
245a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
245b0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 5b 70  olumns in the [p
245c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
245d0 74 5d 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20  t] S,.**        
245e0 20 20 20 6f 72 20 69 66 20 74 68 65 20 4e 74 68     or if the Nth
245f0 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
24600 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  an expression or
24610 20 73 75 62 71 75 65 72 79 20 72 61 74 68 65 72   subquery rather
24620 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
24630 61 6e 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  an a table colum
24640 6e 2c 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72  n, or if a memor
24650 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
24660 6c 75 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  lure.**         
24670 20 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20    occurs during 
24680 65 6e 63 6f 64 69 6e 67 20 63 6f 6e 76 65 72 73  encoding convers
24690 69 6f 6e 73 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  ions, then.**   
246a0 20 20 20 20 20 20 20 20 63 61 6c 6c 73 20 74 6f          calls to
246b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
246c0 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20  _decltype(S,N)] 
246d0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  or.**           
246e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
246f0 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d  decltype16(S,N)]
24700 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f   return NULL..*/
24710 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
24720 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
24730 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
24740 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
24750 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
24760 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
24770 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
24780 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24790 45 46 3a 20 20 45 76 61 6c 75 61 74 65 20 41 6e  EF:  Evaluate An
247a0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b   SQL Statement {
247b0 46 31 33 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 41 66  F13200}.**.** Af
247c0 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
247d0 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
247e0 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
247f0 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  ng either.** [sq
24800 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
24810 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
24820 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
24830 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65  or one of the le
24840 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
24850 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
24860 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
24870 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
24880 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
24890 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  * must be called
248a0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
248b0 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  es to evaluate t
248c0 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  he statement..**
248d0 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
248e0 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
248f0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  of the sqlite3_s
24900 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
24910 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
24920 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
24930 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
24940 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
24950 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a  "v2" interface.*
24960 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
24970 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
24980 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
24990 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
249a0 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
249b0 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f  erface [sqlite3_
249c0 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
249d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
249e0 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
249f0 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32  f the.** new "v2
24a00 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
24a10 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
24a20 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
24a30 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
24a40 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
24a50 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
24a60 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
24a70 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
24a80 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
24a90 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
24aa0 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
24ab0 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_BUSY],.** [SQL
24ac0 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
24ad0 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
24ae0 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
24af0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
24b00 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
24b10 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
24b20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
24b30 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
24b40 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
24b50 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
24b60 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
24b70 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
24b80 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
24b90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
24ba0 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
24bb0 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
24bc0 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
24bd0 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
24be0 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 65  its job.  If the
24bf0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
24c00 43 4f 4d 4d 49 54 0a 2a 2a 20 6f 72 20 6f 63 63  COMMIT.** or occ
24c10 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
24c20 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
24c30 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
24c40 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
24c50 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
24c60 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
24c70 73 20 6e 6f 74 20 61 20 43 4f 4d 4d 49 54 20 61  s not a COMMIT a
24c80 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
24c90 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74   a.** explicit t
24ca0 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
24cb0 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
24cc0 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
24cd0 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
24ce0 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
24cf0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
24d00 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
24d10 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
24d20 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
24d30 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
24d40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
24d50 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
24d60 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
24d70 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
24d80 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
24d90 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
24da0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
24db0 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
24dc0 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
24dd0 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
24de0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66   state..**.** If
24df0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
24e00 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
24e10 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
24e20 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ta, then [SQLITE
24e30 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75  _ROW].** is retu
24e40 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
24e50 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
24e60 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72   is ready for pr
24e70 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a  ocessing by the.
24e80 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  ** caller. The v
24e90 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
24ea0 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20  essed using the 
24eb0 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
24ec0 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71  unctions]..** sq
24ed0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20  lite3_step() is 
24ee0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20  called again to 
24ef0 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78  retrieve the nex
24f00 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  t row of data..*
24f10 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  *.** [SQLITE_ERR
24f20 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
24f30 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
24f40 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
24f50 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
24f60 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
24f70 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
24f80 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
24f90 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
24fa0 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
24fb0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
24fc0 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
24fd0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
24fe0 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20  msg()]..** With 
24ff0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
25000 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
25010 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
25020 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
25030 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
25040 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
25050 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
25060 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
25070 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
25080 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
25090 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
250a0 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
250b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
250c0 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22  ment].  In the "
250d0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
250e0 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
250f0 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
25100 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
25110 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
25120 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
25130 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
25140 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
25150 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
25160 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
25170 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
25180 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
25190 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
251a0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
251b0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e  .** already been
251c0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
251d0 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20  ze | finalized] 
251e0 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68  or on one that h
251f0 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ad.** previously
25200 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
25210 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c  E_ERROR] or [SQL
25220 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69  ITE_DONE].  Or i
25230 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68  t could.** be th
25240 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20  e case that the 
25250 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
25260 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  nnection is bein
25270 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72  g used by two or
25280 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73  .** more threads
25290 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d   at the same mom
252a0 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a  ent in time..**.
252b0 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
252c0 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
252d0 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
252e0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71  nterface, the sq
252f0 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20  lite3_step().** 
25300 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
25310 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
25320 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45  or code, [SQLITE
25330 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69  _ERROR], followi
25340 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20  ng any.** error 
25350 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
25360 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51  TE_BUSY] and [SQ
25370 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59  LITE_MISUSE].  Y
25380 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20  ou must call.** 
25390 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
253a0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
253b0 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64  nalize()] in ord
253c0 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f  er to find one o
253d0 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  f the.** specifi
253e0 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
253f0 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63  that better desc
25400 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e  ribes the error.
25410 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61  .** We admit tha
25420 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66  t this is a goof
25430 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70  y design.  The p
25440 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
25450 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  fixed.** with th
25460 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
25470 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72  .  If you prepar
25480 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51  e all of your SQ
25490 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
254a0 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
254b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
254c0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
254d0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
254e0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
254f0 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
25500 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
25510 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25520 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  e16()] interface
25530 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d  s,.** then the m
25540 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
25550 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
25560 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
25570 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
25580 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
25590 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
255a0 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
255b0 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  nded..**.** INVA
255c0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
255d0 31 33 32 30 32 7d 20 20 49 66 20 74 68 65 20 5b  13202}  If the [
255e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
255f0 6e 74 5d 20 53 20 69 73 20 72 65 61 64 79 20 74  nt] S is ready t
25600 6f 20 62 65 20 72 75 6e 2c 20 74 68 65 6e 0a 2a  o be run, then.*
25610 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
25620 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 61 64  ite3_step(S)] ad
25630 76 61 6e 63 65 73 20 74 68 61 74 20 70 72 65 70  vances that prep
25640 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
25650 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ntil.**         
25660 20 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72 20    completion or 
25670 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 61 64  until it is read
25680 79 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 6f 74  y to return anot
25690 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65 0a 2a  her row of the.*
256a0 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 73 75  *           resu
256b0 6c 74 20 73 65 74 2c 20 6f 72 20 75 6e 74 69 6c  lt set, or until
256c0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74   an [sqlite3_int
256d0 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75  errupt | interru
256e0 70 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  pt].**          
256f0 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65   or a run-time e
25700 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a  rror occurs..**.
25710 2a 2a 20 7b 46 31 35 33 30 34 7d 20 20 57 68 65  ** {F15304}  Whe
25720 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  n a call to [sql
25730 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 63 61  ite3_step(S)] ca
25740 75 73 65 73 20 74 68 65 20 5b 70 72 65 70 61 72  uses the [prepar
25750 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
25760 20 20 20 20 20 20 20 20 20 20 20 53 20 74 6f 20             S to 
25770 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
25780 6e 2c 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  n, the function 
25790 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
257a0 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  DONE]..**.** {F1
257b0 35 33 30 36 7d 20 20 57 68 65 6e 20 61 20 63 61  5306}  When a ca
257c0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
257d0 74 65 70 28 53 29 5d 20 73 74 6f 70 73 20 62 65  tep(S)] stops be
257e0 63 61 75 73 65 20 69 74 20 69 73 20 72 65 61 64  cause it is read
257f0 79 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  y to.**         
25800 20 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72    return another
25810 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
25820 6c 74 20 73 65 74 2c 20 69 74 20 72 65 74 75 72  lt set, it retur
25830 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2e  ns [SQLITE_ROW].
25840 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30 38 7d 20  .**.** {F15308} 
25850 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73   If a call to [s
25860 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
25870 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e 0a 2a 2a  encounters an.**
25880 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
25890 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20  te3_interrupt | 
258a0 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61 20  interrupt] or a 
258b0 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 2c 0a  run-time error,.
258c0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 20  **           it 
258d0 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
258e0 70 72 69 61 74 65 20 65 72 72 6f 72 20 63 6f 64  priate error cod
258f0 65 20 74 68 61 74 20 69 73 20 6e 6f 74 20 6f 6e  e that is not on
25900 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  e of.**         
25910 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 5b    [SQLITE_OK], [
25920 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 6f 72 20  SQLITE_ROW], or 
25930 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a  [SQLITE_DONE]..*
25940 2a 0a 2a 2a 20 7b 46 31 35 33 31 30 7d 20 20 49  *.** {F15310}  I
25950 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e  f an [sqlite3_in
25960 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72  terrupt | interr
25970 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69  upt] or a run-ti
25980 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20  me error.**     
25990 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 72        occurs dur
259a0 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  ing a call to [s
259b0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 0a  qlite3_step(S)].
259c0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66 6f 72  **           for
259d0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
259e0 74 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74 65  tement] S create
259f0 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
25a00 20 20 20 20 20 6c 65 67 61 63 79 20 69 6e 74 65       legacy inte
25a10 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
25a20 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a  prepare()] or.**
25a30 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
25a40 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
25a50 2c 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74  , then the funct
25a60 69 6f 6e 20 72 65 74 75 72 6e 73 20 65 69 74 68  ion returns eith
25a70 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  er.**           
25a80 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
25a90 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f  [SQLITE_BUSY], o
25aa0 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
25ab0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
25ac0 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
25ad0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
25ae0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
25af0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
25b00 65 73 75 6c 74 20 73 65 74 20 7b 46 31 33 37 37  esult set {F1377
25b10 30 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73  0}.**.** Returns
25b20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76   the number of v
25b30 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75 72  alues in the cur
25b40 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
25b50 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a  result set..**.*
25b60 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
25b70 0a 2a 2a 20 7b 46 31 33 37 37 31 7d 20 20 41 66  .** {F13771}  Af
25b80 74 65 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  ter a call to [s
25b90 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
25ba0 74 68 61 74 20 72 65 74 75 72 6e 73 20 5b 53 51  that returns [SQ
25bb0 4c 49 54 45 5f 52 4f 57 5d 2c 0a 2a 2a 20 20 20  LITE_ROW],.**   
25bc0 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c          the [sql
25bd0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
25be0 53 29 5d 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  S)] routine will
25bf0 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
25c00 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20   value.**       
25c10 20 20 20 20 61 73 20 74 68 65 20 5b 73 71 6c 69      as the [sqli
25c20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
25c30 28 53 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  (S)] function..*
25c40 2a 0a 2a 2a 20 7b 46 31 33 37 37 32 7d 20 20 41  *.** {F13772}  A
25c50 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
25c60 65 70 28 53 29 5d 20 68 61 73 20 72 65 74 75 72  ep(S)] has retur
25c70 6e 65 64 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  ned any value ot
25c80 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  her than.**     
25c90 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f        [SQLITE_RO
25ca0 57 5d 20 6f 72 20 62 65 66 6f 72 65 20 5b 73 71  W] or before [sq
25cb0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
25cc0 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  as been called o
25cd0 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
25ce0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
25cf0 74 65 6d 65 6e 74 5d 20 66 6f 72 20 74 68 65 20  tement] for the 
25d00 66 69 72 73 74 20 74 69 6d 65 20 73 69 6e 63 65  first time since
25d10 20 69 74 20 77 61 73 0a 2a 2a 20 20 20 20 20 20   it was.**      
25d20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72       [sqlite3_pr
25d30 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
25d40 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
25d50 73 65 74 20 7c 20 72 65 73 65 74 5d 2c 0a 2a 2a  set | reset],.**
25d60 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b             the [
25d70 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
25d80 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e 65 20 72  nt(S)] routine r
25d90 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a  eturns zero..*/.
25da0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
25db0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
25dc0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
25dd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
25de0 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
25df0 70 65 73 20 7b 46 31 30 32 36 35 7d 0a 2a 2a 20  pes {F10265}.** 
25e00 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
25e10 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  _TEXT.**.** {F10
25e20 32 36 36 7d 20 45 76 65 72 79 20 76 61 6c 75 65  266} Every value
25e30 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f   in SQLite has o
25e40 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61  ne of five funda
25e50 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73  mental datatypes
25e60 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
25e70 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e  <li> 64-bit sign
25e80 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c  ed integer.** <l
25e90 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66  i> 64-bit IEEE f
25ea0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
25eb0 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72  mber.** <li> str
25ec0 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42  ing.** <li> BLOB
25ed0 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a  .** <li> NULL.**
25ee0 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a   </ul> {END}.**.
25ef0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
25f00 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72  ts are codes for
25f10 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74   each of those t
25f20 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ypes..**.** Note
25f30 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45   that the SQLITE
25f40 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77  _TEXT constant w
25f50 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20  as also used in 
25f60 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
25f70 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65  .** for a comple
25f80 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d  tely different m
25f90 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72  eaning.  Softwar
25fa0 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
25fb0 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c  inst both.** SQL
25fc0 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e  ite version 2 an
25fd0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
25fe0 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51   3 should use SQ
25ff0 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a  LITE3_TEXT, not.
26000 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
26010 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
26020 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
26030 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
26040 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
26050 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
26060 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
26070 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
26080 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
26090 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
260a0 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
260b0 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
260c0 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
260d0 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
260e0 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
260f0 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c  3REF: Result Val
26100 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79  ues From A Query
26110 20 7b 46 31 33 38 30 30 7d 0a 2a 2a 20 4b 45 59   {F13800}.** KEY
26120 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
26130 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
26140 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
26150 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22  tines form the "
26160 72 65 73 75 6c 74 20 73 65 74 20 71 75 65 72 79  result set query
26170 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
26180 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
26190 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
261a0 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e  tion about a sin
261b0 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
261c0 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73  e current.** res
261d0 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
261e0 72 79 2e 20 20 49 6e 20 65 76 65 72 79 20 63 61  ry.  In every ca
261f0 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
26200 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
26210 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
26220 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26230 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
26240 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
26250 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
26260 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
26270 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
26280 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
26290 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
262a0 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
262b0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
262c0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
262d0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
262e0 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
262f0 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
26300 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
26310 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
26320 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
26330 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
26340 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  0..**.** If the 
26350 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
26360 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
26370 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
26380 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
26390 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
263a0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
263b0 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
263c0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
263d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
263e0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
263f0 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
26400 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
26410 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
26420 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
26430 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
26440 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
26450 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
26460 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
26470 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
26480 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
26490 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
264a0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
264b0 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
264c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
264d0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
264e0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
264f0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
26500 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
26510 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
26520 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
26530 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
26540 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
26550 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
26560 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
26570 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
26580 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
26590 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
265a0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
265b0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
265c0 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
265d0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
265e0 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
265f0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
26600 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
26610 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
26620 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
26630 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
26640 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
26650 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
26660 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
26670 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
26680 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
26690 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75  olumn.  The retu
266a0 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
266b0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
266c0 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
266d0 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
266e0 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
266f0 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
26700 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76  TE_NULL].  The v
26710 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
26720 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
26730 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
26740 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
26750 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65  no type.** conve
26760 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
26770 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65  rred as describe
26780 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20  d below.  After 
26790 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
267a0 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n,.** the value 
267b0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
267c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
267d0 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
267e0 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
267f0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
26800 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
26810 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
26820 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
26830 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
26840 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
26850 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  *.** If the resu
26860 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
26870 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
26880 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
26890 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
268a0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
268b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
268c0 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
268d0 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49   or string..** I
268e0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
268f0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
26900 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
26910 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
26920 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
26930 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
26940 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
26950 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
26960 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73  s..** If the res
26970 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
26980 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
26990 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
269a0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
269b0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
269c0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
269d0 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
269e0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
269f0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
26a00 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
26a10 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68  at string..** Th
26a20 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
26a30 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
26a40 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
26a50 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64  nator at the end
26a60 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
26a70 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a  g.  For clarity:
26a80 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
26a90 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ned is the numbe
26aa0 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
26ab0 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
26ac0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
26ad0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
26ae0 20 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   Strings returne
26af0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
26b00 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
26b10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
26b20 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
26b30 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
26b40 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74  re always zero t
26b50 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20  erminated.  The 
26b60 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
26b70 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
26b80 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
26b90 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 62 6c 6f   zero-length blo
26ba0 62 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  b is an arbitrar
26bb0 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f  y.** pointer, po
26bc0 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55  ssibly even a NU
26bd0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
26be0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
26bf0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
26c00 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
26c10 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r to sqlite3_col
26c20 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62  umn_bytes().** b
26c30 75 74 20 6c 65 61 76 65 73 20 74 68 65 20 72 65  ut leaves the re
26c40 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69  sult in UTF-16 i
26c50 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
26c60 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55  der instead of U
26c70 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a 65 72  TF-8..** The zer
26c80 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20  o terminator is 
26c90 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  not included in 
26ca0 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a  this count..**.*
26cb0 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74  * The object ret
26cc0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
26cd0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
26ce0 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
26cf0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
26d00 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
26d10 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  An unprotected s
26d20 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
26d30 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ect.** may only 
26d40 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71  be used with [sq
26d50 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
26d60 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
26d70 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
26d80 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
26d90 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
26da0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
26db0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
26dc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
26dd0 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
26de0 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
26df0 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
26e00 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
26e10 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
26e20 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
26e30 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
26e40 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
26e50 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
26e60 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ], then the beha
26e70 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
26e80 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  d..**.** These r
26e90 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
26ea0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
26eb0 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
26ec0 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20  priate.  For.** 
26ed0 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
26ee0 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
26ef0 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
26f00 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
26f10 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
26f20 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
26f30 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
26f40 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70   internally to p
26f50 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f  erform the.** co
26f60 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74  nversion automat
26f70 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c  ically.  The fol
26f80 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
26f90 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
26fa0 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
26fb0 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
26fc0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
26fd0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
26fe0 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
26ff0 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
27000 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
27010 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
27020 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
27030 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
27040 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
27050 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
27060 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
27070 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
27080 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
27090 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
270a0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
270b0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
270c0 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
270d0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
270e0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
270f0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
27100 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
27110 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
27120 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
27130 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
27140 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
27150 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
27160 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
27170 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
27180 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
27190 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
271a0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
271b0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
271c0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
271d0 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
271e0 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
271f0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
27200 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
27210 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
27220 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
27230 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
27240 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
27250 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
27260 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
27270 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
27280 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
27290 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
272a0 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
272b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
272c0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
272d0 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
272e0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
272f0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
27300 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
27310 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
27320 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
27330 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
27340 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
27350 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
27360 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
27370 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
27380 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
27390 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
273a0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
273b0 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
273c0 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
273d0 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
273e0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
273f0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
27400 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
27410 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
27420 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
27430 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
27440 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  >.**.** The tabl
27450 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
27460 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
27470 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
27480 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
27490 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
274a0 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
274b0 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
274c0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
274d0 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71  as its.** own eq
274e0 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61  uivalent interna
274f0 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65  l routines.  The
27500 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66   atoi() and atof
27510 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  () names are.** 
27520 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c  used in the tabl
27530 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e  e for brevity an
27540 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61  d because they a
27550 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d  re familiar to m
27560 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d  ost.** C program
27570 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  mers..**.** Note
27580 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
27590 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
275a0 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
275b0 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
275c0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
275d0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
275e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
275f0 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
27600 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
27610 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
27620 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
27630 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
27640 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
27650 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
27660 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
27670 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
27680 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
27690 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
276a0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
276b0 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
276c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
276d0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
276e0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
276f0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
27700 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
27710 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
27720 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
27730 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
27740 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
27750 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
27760 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
27770 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
27780 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
27790 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
277a0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
277b0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
277c0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
277d0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
277e0 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
277f0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
27800 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
27810 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
27820 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
27830 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
27840 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
27850 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
27860 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
27870 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
27880 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
27890 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
278a0 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73  *.** Conversions
278b0 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
278c0 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
278d0 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
278e0 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
278f0 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
27900 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
27910 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
27920 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
27930 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
27940 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
27950 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f  ointer points to
27960 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20   will have been 
27970 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72  modified.  Other
27980 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e   kinds.** of con
27990 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65  version are done
279a0 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69   in place when i
279b0 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62  t is possible, b
279c0 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65  ut sometimes the
279d0 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73  y.** are not pos
279e0 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f  sible and in tho
279f0 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70  se cases prior p
27a00 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61  ointers are inva
27a10 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  lidated..**.** T
27a20 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61  he safest and ea
27a30 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65  siest to remembe
27a40 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  r policy is to i
27a50 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
27a60 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
27a70 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
27a80 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
27a90 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
27aa0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
27ab0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
27ac0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
27ad0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
27ae0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
27af0 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
27b00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27b10 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
27b20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
27b30 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
27b40 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
27b50 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
27b60 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
27b70 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
27b80 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
27b90 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
27ba0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
27bb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
27bc0 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
27bd0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
27be0 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
27bf0 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
27c00 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
27c10 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
27c20 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
27c30 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
27c40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27c50 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
27c60 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
27c70 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
27c80 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
27c90 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
27ca0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
27cb0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
27cc0 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
27cd0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
27ce0 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
27cf0 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
27d00 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
27d10 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
27d20 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
27d30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
27d40 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  s()..**.** The p
27d50 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
27d60 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
27d70 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
27d80 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
27d90 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
27da0 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
27db0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
27dc0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
27dd0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
27de0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
27df0 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72  lled.  The memor
27e00 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
27e10 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
27e20 61 6e 64 20 62 6c 6f 62 73 20 69 73 20 66 72 65  and blobs is fre
27e30 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
27e40 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e  .  Do <b>not</b>
27e50 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
27e60 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  rs returned.** [
27e70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
27e80 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
27e90 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
27ea0 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
27eb0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
27ec0 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72  **.** If a memor
27ed0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
27ee0 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
27ef0 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
27f00 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
27f10 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
27f20 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
27f30 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
27f40 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
27f50 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
27f60 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
27f70 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
27f80 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
27f90 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
27fa0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
27fb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
27fc0 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
27fd0 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
27fe0 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  MEM]..**.** INVA
27ff0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
28000 31 33 38 30 33 7d 20 54 68 65 20 5b 73 71 6c 69  13803} The [sqli
28010 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
28020 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
28030 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
28040 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
28050 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
28060 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
28070 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20  sult set for.** 
28080 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72           the [pr
28090 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
280a0 5d 20 53 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20  ] S into a BLOB 
280b0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
280c0 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70   a.**          p
280d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ointer to the co
280e0 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a  nverted value..*
280f0 2a 0a 2a 2a 20 7b 46 31 33 38 30 36 7d 20 54 68  *.** {F13806} Th
28100 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
28110 6e 5f 62 79 74 65 73 28 53 2c 4e 29 5d 20 69 6e  n_bytes(S,N)] in
28120 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
28130 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
28140 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
28150 69 6e 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  in the BLOB or s
28160 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65  tring (exclusive
28170 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
28180 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61      zero termina
28190 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e  tor on the strin
281a0 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75  g) that was retu
281b0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20  rned by the.**  
281c0 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63          most rec
281d0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
281e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
281f0 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  (S,N)] or.**    
28200 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
28210 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d  olumn_text(S,N)]
28220 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 39 7d  ..**.** {F13809}
28230 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
28240 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 53 2c 4e  lumn_bytes16(S,N
28250 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
28260 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
28270 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62       number of b
28280 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
28290 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66  ng (exclusive of
282a0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
282b0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
282c0 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20   on the string) 
282d0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
282e0 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
282f0 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74       most recent
28300 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
28310 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
28320 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  S,N)]..**.** {F1
28330 33 38 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  3812} The [sqlit
28340 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
28350 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
28360 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
28370 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f            Nth co
28380 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
28390 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
283a0 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68  esult set for th
283b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
283c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
283d0 74 5d 20 53 20 69 6e 74 6f 20 61 20 66 6c 6f 61  t] S into a floa
283e0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
283f0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
28400 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
28410 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a  of that value..*
28420 2a 0a 2a 2a 20 7b 46 31 33 38 31 35 7d 20 54 68  *.** {F13815} Th
28430 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
28440 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20 69 6e 74 65  n_int(S,N)] inte
28450 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
28460 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
28470 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  th column in the
28480 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
28490 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66  the result set f
284a0 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
284b0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
284c0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
284d0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
284e0 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20  nteger and.**   
284f0 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 74         returns t
28500 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73  he lower 32 bits
28510 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
28520 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 38 7d  ..**.** {F13818}
28530 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
28540 6c 75 6d 6e 5f 69 6e 74 36 34 28 53 2c 4e 29 5d  lumn_int64(S,N)]
28550 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
28560 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
28570 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
28580 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
28590 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
285a0 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  set for the.**  
285b0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
285c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
285d0 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67  nto a 64-bit sig
285e0 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a  ned integer and.
285f0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
28600 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  rns a copy of th
28610 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  at integer..**.*
28620 2a 20 7b 46 31 33 38 32 31 7d 20 54 68 65 20 5b  * {F13821} The [
28630 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
28640 65 78 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ext(S,N)] interf
28650 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
28660 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
28670 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
28680 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
28690 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
286a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
286b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
286c0 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 7a  ment] S into a z
286d0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
286e0 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20  TF-8.**         
286f0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
28700 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
28710 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
28720 0a 2a 2a 20 7b 46 31 33 38 32 34 7d 20 54 68 65  .** {F13824} The
28730 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
28740 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 20 69 6e  _text16(S,N)] in
28750 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
28760 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
28770 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
28780 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
28790 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
287a0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
287b0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
287c0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
287d0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
287e0 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20  ed 2-byte.**    
287f0 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54        aligned UT
28800 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
28810 20 6f 72 64 65 72 20 73 74 72 69 6e 67 20 61 6e   order string an
28820 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  d returns.**    
28830 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65 72 20        a pointer 
28840 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
28850 2a 2a 0a 2a 2a 20 7b 46 31 33 38 32 37 7d 20 54  **.** {F13827} T
28860 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
28870 6d 6e 5f 74 79 70 65 28 53 2c 4e 29 5d 20 69 6e  mn_type(S,N)] in
28880 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
28890 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20  **          one 
288a0 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  of [SQLITE_NULL]
288b0 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  , [SQLITE_INTEGE
288c0 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  R], [SQLITE_FLOA
288d0 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  T],.**          
288e0 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f  [SQLITE_TEXT], o
288f0 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20  r [SQLITE_BLOB] 
28900 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  as appropriate f
28910 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  or.**          t
28920 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e  he Nth column in
28930 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
28940 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
28950 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
28960 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64     the [prepared
28970 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
28980 2a 0a 2a 2a 20 7b 46 31 33 38 33 30 7d 20 54 68  *.** {F13830} Th
28990 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
289a0 6e 5f 76 61 6c 75 65 28 53 2c 4e 29 5d 20 69 6e  n_value(S,N)] in
289b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
289c0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f  a.**          po
289d0 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 75 6e 70  inter to an [unp
289e0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
289f0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
28a00 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
28a10 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
28a20 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
28a30 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
28a40 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
28a50 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64     the [prepared
28a60 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
28a70 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
28a80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
28a90 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
28aa0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
28ab0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
28ac0 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ytes(sqlite3_stm
28ad0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
28ae0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
28af0 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  n_bytes16(sqlite
28b00 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
28b10 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  l);.double sqlit
28b20 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
28b30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
28b40 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
28b50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
28b60 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
28b70 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
28b80 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
28b90 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73  3_column_int64(s
28ba0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
28bb0 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75  t iCol);.const u
28bc0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
28bd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
28be0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
28bf0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
28c00 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
28c10 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71  column_text16(sq
28c20 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
28c30 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
28c40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
28c50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
28c60 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
28c70 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33  3_value *sqlite3
28c80 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71  _column_value(sq
28c90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
28ca0 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   iCol);../*.** C
28cb0 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79  API3REF: Destroy
28cc0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
28cd0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46 31  ement Object {F1
28ce0 33 33 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  3300}.**.** The 
28cf0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
28d00 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
28d10 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
28d20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
28d30 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68  ement]..** If th
28d40 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
28d50 65 78 65 63 75 74 65 64 20 73 75 63 63 65 73 73  executed success
28d60 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65  fully or not exe
28d70 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68  cuted at all, th
28d80 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20  en.** SQLITE_OK 
28d90 69 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20  is returned. If 
28da0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
28db0 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65   statement faile
28dc0 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72  d then an.** [er
28dd0 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78  ror code] or [ex
28de0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
28df0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
28e00 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
28e10 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ne can be called
28e20 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75   at any point du
28e30 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ring the executi
28e40 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72  on of the.** [pr
28e50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28e60 5d 2e 20 20 49 66 20 74 68 65 20 76 69 72 74 75  ].  If the virtu
28e70 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e  al machine has n
28e80 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  ot.** completed 
28e90 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74  execution when t
28ea0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63  his routine is c
28eb0 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c  alled, that is l
28ec0 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ike.** encounter
28ed0 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  ing an error or 
28ee0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  an [sqlite3_inte
28ef0 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70  rrupt | interrup
28f00 74 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74  t]..** Incomplet
28f10 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 65  e updates may be
28f20 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64   rolled back and
28f30 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61   transactions ca
28f40 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e  nceled,.** depen
28f50 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63  ding on the circ
28f60 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74  umstances, and t
28f70 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  he.** [error cod
28f80 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c  e] returned will
28f90 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52   be [SQLITE_ABOR
28fa0 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  T]..**.** INVARI
28fb0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 31  ANTS:.**.** {F11
28fc0 33 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  302} The [sqlite
28fd0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69  3_finalize(S)] i
28fe0 6e 74 65 72 66 61 63 65 20 64 65 73 74 72 6f 79  nterface destroy
28ff0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
29000 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
29010 65 6d 65 6e 74 5d 20 53 20 61 6e 64 20 72 65 6c  ement] S and rel
29020 65 61 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 20 20  eases all.**    
29030 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64        memory and
29040 20 66 69 6c 65 20 72 65 73 6f 75 72 63 65 73 20   file resources 
29050 68 65 6c 64 20 62 79 20 74 68 61 74 20 6f 62 6a  held by that obj
29060 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33  ect..**.** {F113
29070 30 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20  04} If the most 
29080 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
29090 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
290a0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
290b0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
290c0 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
290d0 72 6e 65 64 20 61 6e 20 65 72 72 6f 72 2c 0a 2a  rned an error,.*
290e0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
290f0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
29100 65 28 53 29 5d 20 72 65 74 75 72 6e 73 20 74 68  e(S)] returns th
29110 61 74 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a 2a  at same error..*
29120 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
29130 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
29140 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
29150 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
29160 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
29170 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20  tatement Object 
29180 7b 46 31 33 33 33 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F13330}.**.** T
29190 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
291a0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
291b0 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
291c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
291d0 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
291e0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
291f0 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
29200 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
29210 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73  ed..** Any SQL s
29220 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c  tatement variabl
29230 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75  es that had valu
29240 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d  es bound to them
29250 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73   using.** the [s
29260 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
29270 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
29280 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20  *() API] retain 
29290 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a  their values..**
292a0 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c   Use [sqlite3_cl
292b0 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20  ear_bindings()] 
292c0 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e  to reset the bin
292d0 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  dings..**.** {F1
292e0 31 33 33 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  1332} The [sqlit
292f0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
29300 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68  erface resets th
29310 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
29320 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20  ement] S.**     
29330 20 20 20 20 20 62 61 63 6b 20 74 6f 20 74 68 65       back to the
29340 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
29350 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
29360 20 7b 46 31 31 33 33 34 7d 20 49 66 20 74 68 65   {F11334} If the
29370 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
29380 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
29390 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
293a0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
293b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
293c0 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
293d0 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
293e0 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20  TE_DONE],.**    
293f0 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73 71 6c        or if [sql
29400 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
29410 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
29420 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
29430 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
29440 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
29450 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
29460 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
29470 7b 46 31 31 33 33 36 7d 20 49 66 20 74 68 65 20  {F11336} If the 
29480 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
29490 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
294a0 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
294b0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
294c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
294d0 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
294e0 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  ror, then.**    
294f0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
29500 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
29510 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
29520 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
29530 0a 2a 2a 20 7b 46 31 31 33 33 38 7d 20 54 68 65  .** {F11338} The
29540 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
29550 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
29560 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
29570 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20  e values.**     
29580 20 20 20 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c       of any [sql
29590 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
295a0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
295b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
295c0 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] S..*/.int s
295d0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
295e0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
295f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
29600 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
29610 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
29620 69 6f 6e 73 20 7b 46 31 36 31 30 30 7d 0a 2a 2a  ions {F16100}.**
29630 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
29640 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
29650 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f  utines}.** KEYWO
29660 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
29670 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
29680 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f  nction}.** KEYWO
29690 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
296a0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
296b0 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54  nctions}.**.** T
296c0 68 65 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f  hese two functio
296d0 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79  ns (collectively
296e0 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74   known as "funct
296f0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
29700 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75  tines").** are u
29710 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66  sed to add SQL f
29720 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
29730 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64  egates or to red
29740 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69  efine the behavi
29750 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e  or.** of existin
29760 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  g SQL functions 
29770 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  or aggregates.  
29780 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65  The only differe
29790 6e 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a  nce between the.
297a0 2a 2a 20 74 77 6f 20 69 73 20 74 68 61 74 20 74  ** two is that t
297b0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
297c0 74 65 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66  ter, the name of
297d0 20 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 75   the (scalar) fu
297e0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
297f0 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64  regate, is encod
29800 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 20  ed in UTF-8 for 
29810 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
29820 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54  unction() and UT
29830 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  F-16.** for sqli
29840 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
29850 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  ion16()..**.** T
29860 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
29870 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
29880 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
29890 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
298a0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
298b0 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 49 66  to be added.  If
298c0 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 61   a single progra
298d0 6d 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  m uses more than
298e0 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
298f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65   connection inte
29900 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c  rnally, then SQL
29910 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
29920 62 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 64  be added individ
29930 75 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68  ually to.** each
29940 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
29950 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
29960 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
29970 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
29980 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
29990 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f   to be created o
299a0 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20  r.** redefined. 
299b0 20 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   The length of t
299c0 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
299d0 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c  ed to 255 bytes,
299e0 20 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a   exclusive of.**
299f0 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
29a00 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74  ator.  Note that
29a10 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68   the name length
29a20 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74   limit is in byt
29a30 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61  es, not.** chara
29a40 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65  cters.  Any atte
29a50 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
29a60 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
29a70 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
29a80 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53  ill result in [S
29a90 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69  QLITE_ERROR] bei
29aa0 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
29ab0 2a 2a 20 54 68 65 20 74 68 69 72 64 20 70 61 72  ** The third par
29ac0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 75  ameter is the nu
29ad0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
29ae0 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
29af0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
29b00 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 49  gregate takes. I
29b10 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
29b20 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
29b30 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
29b40 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
29b50 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
29b60 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
29b70 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ents..**.** The 
29b80 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
29b90 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63  , eTextRep, spec
29ba0 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53  ifies what.** [S
29bb0 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78  QLITE_UTF8 | tex
29bc0 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73  t encoding] this
29bd0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72   SQL function pr
29be0 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73  efers for.** its
29bf0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 41 6e   parameters.  An
29c00 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  y SQL function i
29c10 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
29c20 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74 6f 20  ould be able to 
29c30 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74  work.** work wit
29c40 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c  h UTF-8, UTF-16l
29c50 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20  e, or UTF-16be. 
29c60 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d   But some implem
29c70 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65  entations may be
29c80 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65  .** more efficie
29c90 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f  nt with one enco
29ca0 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65  ding than anothe
29cb0 72 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f 77 65  r.  It is allowe
29cc0 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
29cd0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
29ce0 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69  nction() or sqli
29cf0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
29d00 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65  ion16() multiple
29d10 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74  .** times with t
29d20 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
29d30 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72   but with differ
29d40 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54  ent values of eT
29d50 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20  extRep..** When 
29d60 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
29d70 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
29d80 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72  same function ar
29d90 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c  e available, SQL
29da0 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b  ite.** will pick
29db0 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e   the one that in
29dc0 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74  volves the least
29dd0 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
29de0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49  conversion..** I
29df0 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20  f there is only 
29e00 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65  a single impleme
29e10 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f  ntation which do
29e20 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74  es not care what
29e30 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e   text.** encodin
29e40 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  g is used, then 
29e50 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
29e60 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53  ent should be [S
29e70 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a  QLITE_ANY]..**.*
29e80 2a 20 54 68 65 20 66 69 66 74 68 20 70 61 72 61  * The fifth para
29e90 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69  meter is an arbi
29ea0 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20  trary pointer.  
29eb0 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
29ec0 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e  on of the.** fun
29ed0 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61  ction can gain a
29ee0 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f  ccess to this po
29ef0 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c  inter using [sql
29f00 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
29f10 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76  ]..**.** The sev
29f20 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64  enth, eighth and
29f30 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72   ninth parameter
29f40 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
29f50 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
29f60 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
29f70 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
29f80 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
29f90 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
29fa0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
29fb0 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51  ate. A scalar SQ
29fc0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
29fd0 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
29fe0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75  ation of the xFu
29ff0 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f  nc.** callback o
2a000 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly, NULL pointe
2a010 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73  rs should be pas
2a020 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
2a030 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
2a040 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67  arameters. An ag
2a050 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
2a060 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
2a070 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2a080 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
2a090 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
2a0a0 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64  should be passed
2a0b0 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64   for xFunc. To d
2a0c0 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e  elete an existin
2a0d0 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  g.** SQL functio
2a0e0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
2a0f0 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c  pass NULL for al
2a100 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
2a110 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
2a120 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 74 65  * It is permitte
2a130 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75  d to register mu
2a140 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
2a150 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2a160 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  me.** functions 
2a170 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
2a180 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68  me but with eith
2a190 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d  er differing num
2a1a0 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d  bers of.** argum
2a1b0 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e  ents or differin
2a1c0 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  g preferred text
2a1d0 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c   encodings.  SQL
2a1e0 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
2a1f0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
2a200 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  on most closely 
2a210 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
2a220 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
2a230 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
2a240 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  used..**.** INVA
2a250 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
2a260 31 36 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69  16103} The [sqli
2a270 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2a280 69 6f 6e 31 36 28 29 5d 20 69 6e 74 65 72 66 61  ion16()] interfa
2a290 63 65 20 62 65 68 61 76 65 73 20 65 78 61 63 74  ce behaves exact
2a2a0 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c  ly.**          l
2a2b0 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  ike [sqlite3_cre
2a2c0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
2a2d0 69 6e 20 65 76 65 72 79 20 77 61 79 20 65 78 63  in every way exc
2a2e0 65 70 74 20 74 68 61 74 20 69 74 0a 2a 2a 20 20  ept that it.**  
2a2f0 20 20 20 20 20 20 20 20 69 6e 74 65 72 70 72 65          interpre
2a300 74 73 20 74 68 65 20 7a 46 75 6e 63 74 69 6f 6e  ts the zFunction
2a310 4e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 61 73  Name argument as
2a320 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2a330 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20   UTF-16.**      
2a340 20 20 20 20 6e 61 74 69 76 65 20 62 79 74 65 20      native byte 
2a350 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66  order instead of
2a360 20 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   as zero-termina
2a370 74 65 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a  ted UTF-8..**.**
2a380 20 7b 46 31 36 31 30 36 7d 20 41 20 73 75 63 63   {F16106} A succ
2a390 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
2a3a0 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  n of.**         
2a3b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
2a3c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2a3d0 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e 74 65  X,N,E,...)] inte
2a3e0 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 0a  rface registers.
2a3f0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 72  **          or r
2a400 65 70 6c 61 63 65 73 20 63 61 6c 6c 62 61 63 6b  eplaces callback
2a410 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68   functions in th
2a420 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2a430 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20  ection] D.**    
2a440 20 20 20 20 20 20 75 73 65 64 20 74 6f 20 69 6d        used to im
2a450 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
2a460 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64 20 58  function named X
2a470 20 77 69 74 68 20 4e 20 70 61 72 61 6d 65 74 65   with N paramete
2a480 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  rs.**          a
2a490 6e 64 20 68 61 76 69 6e 67 20 61 20 70 72 65 66  nd having a pref
2a4a0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
2a4b0 69 6e 67 20 6f 66 20 45 2e 0a 2a 2a 0a 2a 2a 20  ing of E..**.** 
2a4c0 7b 46 31 36 31 30 39 7d 20 41 20 73 75 63 63 65  {F16109} A succe
2a4d0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
2a4e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2a4f0 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50  nction(D,X,N,E,P
2a500 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20  ,F,S,L)].**     
2a510 20 20 20 20 20 72 65 70 6c 61 63 65 73 20 74 68       replaces th
2a520 65 20 50 2c 20 46 2c 20 53 2c 20 61 6e 64 20 4c  e P, F, S, and L
2a530 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 61 6e 79   values from any
2a540 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74   prior calls wit
2a550 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  h.**          th
2a560 65 20 73 61 6d 65 20 44 2c 20 58 2c 20 4e 2c 20  e same D, X, N, 
2a570 61 6e 64 20 45 20 76 61 6c 75 65 73 2e 0a 2a 2a  and E values..**
2a580 0a 2a 2a 20 7b 46 31 36 31 31 32 7d 20 54 68 65  .** {F16112} The
2a590 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2a5a0 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e  _function(D,X,..
2a5b0 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61  .)] interface fa
2a5c0 69 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  ils with.**     
2a5d0 20 20 20 20 20 61 20 72 65 74 75 72 6e 20 63 6f       a return co
2a5e0 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52  de of [SQLITE_ER
2a5f0 52 4f 52 5d 20 69 66 20 74 68 65 20 53 51 4c 20  ROR] if the SQL 
2a600 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 20 58 20  function name X 
2a610 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c  is.**          l
2a620 6f 6e 67 65 72 20 74 68 61 6e 20 32 35 35 20 62  onger than 255 b
2a630 79 74 65 73 20 65 78 63 6c 75 73 69 76 65 20 6f  ytes exclusive o
2a640 66 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  f the zero termi
2a650 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  nator..**.** {F1
2a660 36 31 31 38 7d 20 45 69 74 68 65 72 20 46 20 6d  6118} Either F m
2a670 75 73 74 20 62 65 20 4e 55 4c 4c 20 61 6e 64 20  ust be NULL and 
2a680 53 20 61 6e 64 20 4c 20 61 72 65 20 6e 6f 6e 2d  S and L are non-
2a690 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 46 0a 2a  NULL or else F.*
2a6a0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f  *          is no
2a6b0 6e 2d 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64  n-NULL and S and
2a6c0 20 4c 20 61 72 65 20 4e 55 4c 4c 2c 20 6f 74 68   L are NULL, oth
2a6d0 65 72 77 69 73 65 0a 2a 2a 20 20 20 20 20 20 20  erwise.**       
2a6e0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61     [sqlite3_crea
2a6f0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2a700 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 72 65  N,E,P,F,S,L)] re
2a710 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 45 52  turns [SQLITE_ER
2a720 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ROR]..**.** {F16
2a730 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  121} The [sqlite
2a740 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2a750 6e 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  n(D,...)] interf
2a760 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 61  ace fails with a
2a770 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72  n.**          er
2a780 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c  ror code of [SQL
2a790 49 54 45 5f 42 55 53 59 5d 20 69 66 20 74 68 65  ITE_BUSY] if the
2a7a0 72 65 20 65 78 69 73 74 20 5b 70 72 65 70 61 72  re exist [prepar
2a7b0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a  ed statements].*
2a7c0 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 6f 63  *          assoc
2a7d0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
2a7e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2a7f0 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ion] D..**.** {F
2a800 31 36 31 32 34 7d 20 54 68 65 20 5b 73 71 6c 69  16124} The [sqli
2a810 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2a820 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 20  ion(D,X,N,...)] 
2a830 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
2a840 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20  with an.**      
2a850 20 20 20 20 65 72 72 6f 72 20 63 6f 64 65 20 6f      error code o
2a860 66 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  f [SQLITE_ERROR]
2a870 20 69 66 20 70 61 72 61 6d 65 74 65 72 20 4e 20   if parameter N 
2a880 28 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20  (specifying the 
2a890 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20  number.**       
2a8a0 20 20 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20     of arguments 
2a8b0 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
2a8c0 69 6f 6e 20 62 65 69 6e 67 20 72 65 67 69 73 74  ion being regist
2a8d0 65 72 65 64 29 20 69 73 20 6c 65 73 73 0a 2a 2a  ered) is less.**
2a8e0 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 2d            than -
2a8f0 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
2a900 6e 20 31 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  n 127..**.** {F1
2a910 36 31 32 37 7d 20 57 68 65 6e 20 4e 20 69 73 20  6127} When N is 
2a920 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
2a930 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2a940 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2a950 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
2a960 20 20 20 69 6e 74 65 72 66 61 63 65 20 63 61 75     interface cau
2a970 73 65 73 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f  ses callbacks to
2a980 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   be invoked for 
2a990 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2a9a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d  .**          nam
2a9b0 65 64 20 58 20 77 68 65 6e 20 74 68 65 20 6e 75  ed X when the nu
2a9c0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
2a9d0 73 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  s to the SQL fun
2a9e0 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ction is.**     
2a9f0 20 20 20 20 20 65 78 61 63 74 6c 79 20 4e 2e 0a       exactly N..
2aa00 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 30 7d 20 57  **.** {F16130} W
2aa10 68 65 6e 20 4e 20 69 73 20 2d 31 2c 20 74 68 65  hen N is -1, the
2aa20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2aa30 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2aa40 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
2aa50 20 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73    interface caus
2aa60 65 73 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20  es callbacks to 
2aa70 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74  be invoked for t
2aa80 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a  he SQL function.
2aa90 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65  **          name
2aaa0 64 20 58 20 77 69 74 68 20 61 6e 79 20 6e 75 6d  d X with any num
2aab0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
2aac0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 33 7d  ..**.** {F16133}
2aad0 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b   When calls to [
2aae0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2aaf0 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e  unction(D,X,N,..
2ab00 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
2ab10 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c 65  specify multiple
2ab20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2ab30 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
2ab40 63 74 69 6f 6e 20 58 0a 2a 2a 20 20 20 20 20 20  ction X.**      
2ab50 20 20 20 20 61 6e 64 20 77 68 65 6e 20 6f 6e 65      and when one
2ab60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2ab70 68 61 73 20 4e 3e 3d 30 20 61 6e 64 20 74 68 65  has N>=0 and the
2ab80 20 6f 74 68 65 72 20 68 61 73 20 4e 3d 28 2d 31   other has N=(-1
2ab90 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ).**          th
2aba0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2abb0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f   with a non-zero
2abc0 20 4e 20 69 73 20 70 72 65 66 65 72 72 65 64 2e   N is preferred.
2abd0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 33 36 7d 20  .**.** {F16136} 
2abe0 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  When calls to [s
2abf0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2ac00 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e  nction(D,X,N,E,.
2ac10 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
2ac20 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c   specify multipl
2ac30 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2ac40 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
2ac50 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 0a 2a 2a  nction X with.**
2ac60 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61            the sa
2ac70 6d 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  me number of arg
2ac80 75 6d 65 6e 74 73 20 4e 20 62 75 74 20 77 69 74  uments N but wit
2ac90 68 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 20  h different.**  
2aca0 20 20 20 20 20 20 20 20 65 6e 63 6f 64 69 6e 67          encoding
2acb0 73 20 45 2c 20 74 68 65 6e 20 74 68 65 20 69 6d  s E, then the im
2acc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
2acd0 72 65 20 45 20 6d 61 74 63 68 65 73 20 74 68 65  re E matches the
2ace0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74  .**          dat
2acf0 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69  abase encoding i
2ad00 73 20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a  s preferred..**.
2ad10 2a 2a 20 7b 46 31 36 31 33 39 7d 20 46 6f 72 20  ** {F16139} For 
2ad20 61 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  an aggregate SQL
2ad30 20 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 65   function create
2ad40 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
2ad50 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65      [sqlite3_cre
2ad60 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2ad70 2c 4e 2c 45 2c 50 2c 30 2c 53 2c 4c 29 5d 20 74  ,N,E,P,0,S,L)] t
2ad80 68 65 20 66 69 6e 61 6c 69 7a 65 72 0a 2a 2a 20  he finalizer.** 
2ad90 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f           functio
2ada0 6e 20 4c 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  n L will always 
2adb0 62 65 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74  be invoked exact
2adc0 6c 79 20 6f 6e 63 65 20 69 66 20 74 68 65 0a 2a  ly once if the.*
2add0 2a 20 20 20 20 20 20 20 20 20 20 73 74 65 70 20  *          step 
2ade0 66 75 6e 63 74 69 6f 6e 20 53 20 69 73 20 63 61  function S is ca
2adf0 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
2ae00 20 74 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46   times..**.** {F
2ae10 31 36 31 34 32 7d 20 57 68 65 6e 20 53 51 4c 69  16142} When SQLi
2ae20 74 65 20 69 6e 76 6f 6b 65 73 20 65 69 74 68 65  te invokes eithe
2ae30 72 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78  r the xFunc or x
2ae40 53 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 6f 66  Step function of
2ae50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20  .**          an 
2ae60 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2ae70 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2ae80 20 6f 72 20 61 67 67 72 65 67 61 74 65 20 63 72   or aggregate cr
2ae90 65 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  eated.**        
2aea0 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 72    by [sqlite3_cr
2aeb0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2aec0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   or [sqlite3_cre
2aed0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2aee0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ],.**          t
2aef0 68 65 6e 20 74 68 65 20 61 72 72 61 79 20 6f 66  hen the array of
2af00 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2af10 20 6f 62 6a 65 63 74 73 20 70 61 73 73 65 64 20   objects passed 
2af20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  as the.**       
2af30 20 20 20 74 68 69 72 64 20 70 61 72 61 6d 65 74     third paramet
2af40 65 72 20 61 72 65 20 61 6c 77 61 79 73 20 5b 70  er are always [p
2af50 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2af60 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
2af70 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2af80 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2af90 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
2afa0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
2afb0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
2afc0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
2afd0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
2afe0 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
2aff0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
2b000 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2b010 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2b020 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
2b030 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2b040 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2b050 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
2b060 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
2b070 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
2b080 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2b090 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  nction16(.  sqli
2b0a0 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
2b0b0 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e   void *zFunction
2b0c0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
2b0d0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2b0e0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
2b0f0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
2b100 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2b110 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2b120 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2b130 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
2b140 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2b150 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2b160 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
2b170 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2b180 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2b190 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69  REF: Text Encodi
2b1a0 6e 67 73 20 7b 46 31 30 32 36 37 7d 0a 2a 2a 0a  ngs {F10267}.**.
2b1b0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2b1c0 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
2b1d0 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
2b1e0 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
2b1f0 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
2b200 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
2b210 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
2b220 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
2b230 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
2b240 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2b250 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  LE        2.#def
2b260 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2b270 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66  BE        3.#def
2b280 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2b290 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
2b2a0 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
2b2b0 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
2b2c0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
2b2d0 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
2b2e0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2b2f0 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  function only */
2b300 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2b310 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
2b320 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
2b330 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
2b340 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
2b350 41 50 49 33 52 45 46 3a 20 4f 62 73 6f 6c 65 74  API3REF: Obsolet
2b360 65 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  e Functions.**.*
2b370 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
2b380 73 20 61 72 65 20 61 6c 6c 20 6e 6f 77 20 6f 62  s are all now ob
2b390 73 6f 6c 65 74 65 2e 20 20 49 6e 20 6f 72 64 65  solete.  In orde
2b3a0 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a  r to maintain.**
2b3b0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
2b3c0 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c  tibility with ol
2b3d0 64 65 72 20 63 6f 64 65 2c 20 77 65 20 63 6f 6e  der code, we con
2b3e0 74 69 6e 75 65 20 74 6f 20 73 75 70 70 6f 72 74  tinue to support
2b3f0 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69  .** these functi
2b400 6f 6e 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ons.  However, n
2b410 65 77 20 64 65 76 65 6c 6f 70 6d 65 6e 74 20 70  ew development p
2b420 72 6f 6a 65 63 74 73 20 73 68 6f 75 6c 64 20 61  rojects should a
2b430 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
2b440 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2b450 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63  ns.  To help enc
2b460 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f  ourage people to
2b470 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20   avoid.** using 
2b480 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
2b490 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e   we are not goin
2b4a0 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 61  g to tell you wa
2b4b0 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 69  nt they do..*/.i
2b4c0 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
2b4d0 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
2b4e0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 69 6e  e3_context*);.in
2b4f0 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65  t sqlite3_expire
2b500 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  d(sqlite3_stmt*)
2b510 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72  ;.int sqlite3_tr
2b520 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28  ansfer_bindings(
2b530 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73  sqlite3_stmt*, s
2b540 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 69  qlite3_stmt*);.i
2b550 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61  nt sqlite3_globa
2b560 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b  l_recover(void);
2b570 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68  .void sqlite3_th
2b580 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
2b590 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
2b5a0 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
2b5b0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
2b5c0 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f  e3_int64,int),vo
2b5d0 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
2b5e0 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  4);../*.** CAPI3
2b5f0 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
2b600 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
2b610 6d 65 74 65 72 20 56 61 6c 75 65 73 20 7b 46 31  meter Values {F1
2b620 35 31 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  5100}.**.** The 
2b630 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
2b640 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
2b650 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
2b660 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
2b670 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
2b680 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
2b690 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
2b6a0 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
2b6b0 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
2b6c0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
2b6d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
2b6e0 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
2b6f0 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
2b700 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
2b710 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
2b720 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
2b730 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
2b740 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2b750 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2b760 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
2b770 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
2b780 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
2b790 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
2b7a0 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68  ates..** The 4th
2b7b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2b7c0 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
2b7d0 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
2b7e0 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f  nters to.** [pro
2b7f0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2b800 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
2b810 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
2b820 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2b830 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
2b840 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2b850 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
2b860 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
2b870 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
2b880 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
2b890 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
2b8a0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
2b8b0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2b8c0 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69  nes work only wi
2b8d0 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  th [protected sq
2b8e0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2b8f0 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  ects..** Any att
2b900 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73  empt to use thes
2b910 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e  e routines on an
2b920 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2b930 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
2b940 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69  object results i
2b950 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
2b960 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  vior..**.** Thes
2b970 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
2b980 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f  just like the co
2b990 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c  rresponding [col
2b9a0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
2b9b0 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20  ions].** except 
2b9c0 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74  that  these rout
2b9d0 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
2b9e0 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  le [protected sq
2b9f0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2ba00 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ect.** pointer i
2ba10 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c  nstead of a [sql
2ba20 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e  ite3_stmt*] poin
2ba30 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67  ter and an integ
2ba40 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  er column number
2ba50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2ba60 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2ba70 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
2ba80 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
2ba90 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
2baa0 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
2bab0 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
2bac0 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73  chine.  The.** s
2bad0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2bae0 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
2baf0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2bb00 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
2bb10 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31  ** extract UTF-1
2bb20 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
2bb30 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
2bb40 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
2bb50 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  tively..**.** Th
2bb60 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
2bb70 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
2bb80 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
2bb90 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
2bba0 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
2bbb0 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
2bbc0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
2bbd0 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
2bbe0 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
2bbf0 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
2bc00 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
2bc10 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
2bc20 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
2bc30 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
2bc40 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
2bc50 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
2bc60 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69  ther.** words, i
2bc70 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61  f the value is a
2bc80 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f   string that loo
2bc90 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72  ks like a number
2bca0 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ).** then the co
2bcb0 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
2bcc0 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73  ormed.  Otherwis
2bcd0 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
2bce0 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b  occurs..** The [
2bcf0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
2bd00 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
2bd10 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
2bd20 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  eturned..**.** P
2bd30 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63  lease pay partic
2bd40 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74  ular attention t
2bd50 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20  o the fact that 
2bd60 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75  the pointer retu
2bd70 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
2bd80 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
2bd90 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2bda0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a  lue_text()], or.
2bdb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2bdc0 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20  e_text16()] can 
2bdd0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62  be invalidated b
2bde0 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63  y a subsequent c
2bdf0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2be00 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
2be10 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2be20 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73  e_bytes16()], [s
2be30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2be40 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
2be50 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2be60 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  6()]..**.** Thes
2be70 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
2be80 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
2be90 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61  he same thread a
2bea0 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  s.** the SQL fun
2beb0 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c  ction that suppl
2bec0 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ied the [sqlite3
2bed0 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74  _value*] paramet
2bee0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ers..**.** INVAR
2bef0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
2bf00 35 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  5103} The [sqlit
2bf10 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29  e3_value_blob(V)
2bf20 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2bf30 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2bf40 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
2bf50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2bf60 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 42  bject V into a B
2bf70 4c 4f 42 20 61 6e 64 20 74 68 65 6e 0a 2a 2a 20  LOB and then.** 
2bf80 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
2bf90 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2bfa0 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75  e converted valu
2bfb0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 36  e..**.** {F15106
2bfc0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2bfd0 61 6c 75 65 5f 62 79 74 65 73 28 56 29 5d 20 69  alue_bytes(V)] i
2bfe0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2bff0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2c000 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2c010 20 69 6e 20 74 68 65 20 42 4c 4f 42 20 6f 72 20   in the BLOB or 
2c020 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76  string (exclusiv
2c030 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  e of the.**     
2c040 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e       zero termin
2c050 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69  ator on the stri
2c060 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74  ng) that was ret
2c070 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
2c080 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65           most re
2c090 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2c0a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
2c0b0 28 56 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  (V)] or.**      
2c0c0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c      [sqlite3_val
2c0d0 75 65 5f 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a  ue_text(V)]..**.
2c0e0 2a 2a 20 7b 46 31 35 31 30 39 7d 20 54 68 65 20  ** {F15109} The 
2c0f0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2c100 79 74 65 73 31 36 28 56 29 5d 20 69 6e 74 65 72  ytes16(V)] inter
2c110 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2c120 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
2c130 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2c140 74 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c  the string (excl
2c150 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20  usive of the.** 
2c160 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65           zero te
2c170 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20  rminator on the 
2c180 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73  string) that was
2c190 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2c1a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73  .**          mos
2c1b0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2c1c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2c1d0 74 65 78 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20  text16(V)],.**  
2c1e0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2c1f0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
2c200 56 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  V)], or [sqlite3
2c210 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
2c220 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31  V)]..**.** {F151
2c230 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  12} The [sqlite3
2c240 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29  _value_double(V)
2c250 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2c260 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2c270 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
2c280 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2c290 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 66  bject V into a f
2c2a0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2c2b0 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  lue and.**      
2c2c0 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f      returns a co
2c2d0 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65  py of that value
2c2e0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31 35 7d  ..**.** {F15115}
2c2f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2c300 6c 75 65 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65  lue_int(V)] inte
2c310 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
2c320 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2c330 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2c340 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2c350 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20  V into a 64-bit 
2c360 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
2c370 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  nd.**          r
2c380 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72  eturns the lower
2c390 20 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 74   32 bits of that
2c3a0 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
2c3b0 7b 46 31 35 31 31 38 7d 20 54 68 65 20 5b 73 71  {F15118} The [sq
2c3c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
2c3d0 34 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  4(V)] interface 
2c3e0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2c3f0 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
2c400 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2c410 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
2c420 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64   a 64-bit signed
2c430 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20   integer and.** 
2c440 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
2c450 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20   a copy of that 
2c460 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  integer..**.** {
2c470 46 31 35 31 32 31 7d 20 54 68 65 20 5b 73 71 6c  F15121} The [sql
2c480 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2c490 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
2c4a0 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2c4b0 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
2c4c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2c4d0 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
2c4e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2c4f0 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20   UTF-8.**       
2c500 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65     string and re
2c510 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2c520 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
2c530 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32 34 7d 20 54  **.** {F15124} T
2c540 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2c550 65 5f 74 65 78 74 31 36 28 56 29 5d 20 69 6e 74  e_text16(V)] int
2c560 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2c570 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2c580 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2c590 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2c5a0 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   V into a zero-t
2c5b0 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65  erminated 2-byte
2c5c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69  .**          ali
2c5d0 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69  gned UTF-16 nati
2c5e0 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a  ve byte order.**
2c5f0 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
2c600 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
2c610 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
2c620 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tring..**.** {F1
2c630 35 31 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74  5127} The [sqlit
2c640 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
2c650 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(V)] interface 
2c660 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2c670 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
2c680 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2c690 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
2c6a0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2c6b0 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20  ed 2-byte.**    
2c6c0 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54        aligned UT
2c6d0 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a  F-16 big-endian.
2c6e0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
2c6f0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
2c700 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
2c710 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
2c720 46 31 35 31 33 30 7d 20 54 68 65 20 5b 73 71 6c  F15130} The [sql
2c730 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2c740 36 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  6le(V)] interfac
2c750 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
2c760 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
2c770 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c780 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
2c790 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2c7a0 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20  ated 2-byte.**  
2c7b0 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20          aligned 
2c7c0 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e  UTF-16 little-en
2c7d0 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  dian.**         
2c7e0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2c7f0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2c800 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2c810 0a 2a 2a 20 7b 46 31 35 31 33 33 7d 20 54 68 65  .** {F15133} The
2c820 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2c830 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61  type(V)] interfa
2c840 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  ce returns.**   
2c850 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53         one of [S
2c860 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51  QLITE_NULL], [SQ
2c870 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b  LITE_INTEGER], [
2c880 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a  SQLITE_FLOAT],.*
2c890 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
2c8a0 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51  TE_TEXT], or [SQ
2c8b0 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70  LITE_BLOB] as ap
2c8c0 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a  propriate for.**
2c8d0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73            the [s
2c8e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2c8f0 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ject V..**.** {F
2c900 31 35 31 33 36 7d 20 54 68 65 20 5b 73 71 6c 69  15136} The [sqli
2c910 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
2c920 63 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72  c_type(V)] inter
2c930 66 61 63 65 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  face converts.**
2c940 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70            the [p
2c950 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2c960 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2c970 20 69 6e 74 6f 20 65 69 74 68 65 72 20 61 6e 20   into either an 
2c980 69 6e 74 65 67 65 72 20 6f 72 0a 2a 2a 20 20 20  integer or.**   
2c990 20 20 20 20 20 20 20 61 20 66 6c 6f 61 74 69 6e         a floatin
2c9a0 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 69 66  g point value if
2c9b0 20 69 74 20 63 61 6e 20 64 6f 20 73 6f 20 77 69   it can do so wi
2c9c0 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 0a 2a 2a  thout loss of.**
2c9d0 20 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d            inform
2c9e0 61 74 69 6f 6e 2c 20 61 6e 64 20 72 65 74 75 72  ation, and retur
2c9f0 6e 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  ns one of [SQLIT
2ca00 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20 20  E_NULL],.**     
2ca10 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 4e 54       [SQLITE_INT
2ca20 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46  EGER], [SQLITE_F
2ca30 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
2ca40 45 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  EXT], or.**     
2ca50 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 42 4c 4f       [SQLITE_BLO
2ca60 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74  B] as appropriat
2ca70 65 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  e for the.**    
2ca80 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
2ca90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2caa0 6f 62 6a 65 63 74 20 56 20 61 66 74 65 72 20 74  object V after t
2cab0 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 74  he conversion at
2cac0 74 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  tempt..*/.const 
2cad0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
2cae0 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  lue_blob(sqlite3
2caf0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2cb00 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2cb10 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  s(sqlite3_value*
2cb20 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
2cb30 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c  alue_bytes16(sql
2cb40 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f  ite3_value*);.do
2cb50 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  uble sqlite3_val
2cb60 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  ue_double(sqlite
2cb70 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2cb80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2cb90 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2cba0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
2cbb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
2cbc0 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64(sqlite3_valu
2cbd0 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  e*);.const unsig
2cbe0 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
2cbf0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c  3_value_text(sql
2cc00 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
2cc10 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2cc20 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
2cc30 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2cc40 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2cc50 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2cc60 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
2cc70 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
2cc80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2cc90 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76  xt16be(sqlite3_v
2cca0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2ccb0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
2ccc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2ccd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2cce0 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
2ccf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2cd00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2cd10 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
2cd20 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
2cd30 78 74 20 7b 46 31 36 32 31 30 7d 0a 2a 2a 0a 2a  xt {F16210}.**.*
2cd40 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * The implementa
2cd50 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61 74  tion of aggregat
2cd60 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
2cd70 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  use this routine
2cd80 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20   to allocate.** 
2cd90 61 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  a structure for 
2cda0 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74  storing their st
2cdb0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ate..**.** The f
2cdc0 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
2cdd0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2cde0 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 74 69 6e  context() routin
2cdf0 65 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20  e is called for 
2ce00 61 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20  a.** particular 
2ce10 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c 69 74  aggregate, SQLit
2ce20 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79 74  e allocates nByt
2ce30 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65  es of memory, ze
2ce40 72 6f 65 73 20 6f 75 74 20 74 68 61 74 0a 2a 2a  roes out that.**
2ce50 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74   memory, and ret
2ce60 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2ce70 6f 20 69 74 2e 20 4f 6e 20 73 65 63 6f 6e 64 20  o it. On second 
2ce80 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63  and subsequent c
2ce90 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
2cea0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2ceb0 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73  text() for the s
2cec0 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
2ced0 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c 0a 2a 2a  nction index,.**
2cee0 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
2cef0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 54 68   is returned. Th
2cf00 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2cf10 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74   of the aggregat
2cf20 65 20 63 61 6e 20 75 73 65 0a 2a 2a 20 74 68 65  e can use.** the
2cf30 20 72 65 74 75 72 6e 65 64 20 62 75 66 66 65 72   returned buffer
2cf40 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20 64   to accumulate d
2cf50 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ata..**.** SQLit
2cf60 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
2cf70 66 72 65 65 73 20 74 68 65 20 61 6c 6c 6f 63 61  frees the alloca
2cf80 74 65 64 20 62 75 66 66 65 72 20 77 68 65 6e 20  ted buffer when 
2cf90 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a  the aggregate.**
2cfa0 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
2cfb0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
2cfc0 74 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75  t parameter shou
2cfd0 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20  ld be a copy of 
2cfe0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
2cff0 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75  context | SQL fu
2d000 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20  nction context] 
2d010 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73  that is the firs
2d020 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  t parameter.** t
2d030 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  o the callback r
2d040 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c  outine that impl
2d050 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65  ements the aggre
2d060 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  gate function..*
2d070 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
2d080 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
2d090 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
2d0a0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
2d0b0 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  * the aggregate 
2d0c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
2d0d0 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49  running..**.** I
2d0e0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2d0f0 20 7b 46 31 36 32 31 31 7d 20 54 68 65 20 66 69   {F16211} The fi
2d100 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  rst invocation o
2d110 66 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  f [sqlite3_aggre
2d120 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
2d130 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )] for.**       
2d140 20 20 20 61 20 70 61 72 74 69 63 75 6c 61 72 20     a particular 
2d150 69 6e 73 74 61 6e 63 65 20 6f 66 20 61 6e 20 61  instance of an a
2d160 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
2d170 6e 20 28 66 6f 72 20 61 20 70 61 72 74 69 63 75  n (for a particu
2d180 6c 61 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lar.**          
2d190 63 6f 6e 74 65 78 74 20 43 29 20 63 61 75 73 65  context C) cause
2d1a0 73 20 53 51 4c 69 74 65 20 74 6f 20 61 6c 6c 6f  s SQLite to allo
2d1b0 63 61 74 65 20 4e 20 62 79 74 65 73 20 6f 66 20  cate N bytes of 
2d1c0 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 20 20 20 20 20  memory,.**      
2d1d0 20 20 20 20 7a 65 72 6f 20 74 68 61 74 20 6d 65      zero that me
2d1e0 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e  mory, and return
2d1f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2d200 65 20 61 6c 6c 6f 63 61 74 65 64 20 6d 65 6d 6f  e allocated memo
2d210 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31  ry..**.** {F1621
2d220 33 7d 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61  3} If a memory a
2d230 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
2d240 6f 63 63 75 72 73 20 64 75 72 69 6e 67 0a 2a 2a  occurs during.**
2d250 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2d260 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2d270 74 65 78 74 28 43 2c 4e 29 5d 20 74 68 65 6e 20  text(C,N)] then 
2d280 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  the function ret
2d290 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a 2a 20 7b 46  urns 0..**.** {F
2d2a0 31 36 32 31 35 7d 20 53 65 63 6f 6e 64 20 61 6e  16215} Second an
2d2b0 64 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  d subsequent inv
2d2c0 6f 63 61 74 69 6f 6e 73 20 6f 66 0a 2a 2a 20 20  ocations of.**  
2d2d0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2d2e0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2d2f0 78 74 28 43 2c 4e 29 5d 20 66 6f 72 20 74 68 65  xt(C,N)] for the
2d300 20 73 61 6d 65 20 63 6f 6e 74 65 78 74 20 70 6f   same context po
2d310 69 6e 74 65 72 20 43 0a 2a 2a 20 20 20 20 20 20  inter C.**      
2d320 20 20 20 20 69 67 6e 6f 72 65 20 74 68 65 20 4e      ignore the N
2d330 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
2d340 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20  eturn a pointer 
2d350 74 6f 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  to the same.**  
2d360 20 20 20 20 20 20 20 20 62 6c 6f 63 6b 20 6f 66          block of
2d370 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
2d380 20 62 79 20 74 68 65 20 66 69 72 73 74 20 69 6e   by the first in
2d390 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  vocation..**.** 
2d3a0 7b 46 31 36 32 31 37 7d 20 54 68 65 20 6d 65 6d  {F16217} The mem
2d3b0 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ory allocated by
2d3c0 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
2d3d0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
2d3e0 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] is.**         
2d3f0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
2d400 72 65 65 64 20 6f 6e 20 74 68 65 20 6e 65 78 74  reed on the next
2d410 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2d420 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 20 20  3_reset()].**   
2d430 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
2d440 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 66  e3_finalize()] f
2d450 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
2d460 20 73 74 61 74 65 6d 65 6e 74 5d 20 63 6f 6e 74   statement] cont
2d470 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  aining.**       
2d480 20 20 20 74 68 65 20 61 67 67 72 65 67 61 74 65     the aggregate
2d490 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69   function associ
2d4a0 61 74 65 64 20 77 69 74 68 20 63 6f 6e 74 65 78  ated with contex
2d4b0 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  t C..*/.void *sq
2d4c0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2d4d0 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
2d4e0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
2d4f0 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
2d500 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
2d510 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20  a For Functions 
2d520 7b 46 31 36 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F16240}.**.** T
2d530 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  he sqlite3_user_
2d540 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
2d550 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
2d560 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
2d570 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70  r that was the p
2d580 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74  UserData paramet
2d590 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61  er (the 5th para
2d5a0 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
2d5b0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2d5c0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
2d5d0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
2d5e0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2d5f0 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
2d600 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
2d610 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
2d620 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
2d630 20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d   function. {END}
2d640 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2d650 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
2d660 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2d670 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2d680 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
2d690 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2d6a0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
2d6b0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
2d6c0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 34 33  S:.**.** {F16243
2d6d0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75  } The [sqlite3_u
2d6e0 73 65 72 5f 64 61 74 61 28 43 29 5d 20 69 6e 74  ser_data(C)] int
2d6f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2d700 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
2d710 20 20 20 20 20 20 20 20 20 50 20 70 6f 69 6e 74           P point
2d720 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  er from the [sql
2d730 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2d740 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  tion(D,X,N,E,P,F
2d750 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,S,L)].**       
2d760 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63     or [sqlite3_c
2d770 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2d780 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
2d790 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20  )] call that.** 
2d7a0 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65           registe
2d7b0 72 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  red the SQL func
2d7c0 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20  tion associated 
2d7d0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f  with [sqlite3_co
2d7e0 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69  ntext] C..*/.voi
2d7f0 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  d *sqlite3_user_
2d800 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
2d810 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
2d820 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
2d830 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72  e Connection For
2d840 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 36 32   Functions {F162
2d850 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  50}.**.** The sq
2d860 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2d870 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
2d880 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
2d890 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
2d8a0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
2d8b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d8c0 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
2d8d0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
2d8e0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2d8f0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
2d900 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2d910 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2d920 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
2d930 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
2d940 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
2d950 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
2d960 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2d970 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2d980 2a 20 7b 46 31 36 32 35 33 7d 20 54 68 65 20 5b  * {F16253} The [
2d990 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
2d9a0 64 62 5f 68 61 6e 64 6c 65 28 43 29 5d 20 69 6e  db_handle(C)] in
2d9b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2d9c0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
2d9d0 20 20 20 20 20 20 20 20 20 20 44 20 70 6f 69 6e            D poin
2d9e0 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ter from the [sq
2d9f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2da00 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
2da10 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20  F,S,L)].**      
2da20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
2da30 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2da40 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  6(D,X,N,E,P,F,S,
2da50 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a  L)] call that.**
2da60 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
2da70 65 72 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e  ered the SQL fun
2da80 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64  ction associated
2da90 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63   with [sqlite3_c
2daa0 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71  ontext] C..*/.sq
2dab0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
2dac0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
2dad0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2dae0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2daf0 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
2db00 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b 46 31  xiliary Data {F1
2db10 36 32 37 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  6270}.**.** The 
2db20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75  following two fu
2db30 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75  nctions may be u
2db40 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51  sed by scalar SQ
2db50 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a  L functions to.*
2db60 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61  * associate meta
2db70 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65  data with argume
2db80 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68  nt values. If th
2db90 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20  e same value is 
2dba0 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c  passed to.** mul
2dbb0 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e  tiple invocation
2dbc0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51  s of the same SQ
2dbd0 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e  L function durin
2dbe0 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f  g query executio
2dbf0 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65  n, under.** some
2dc00 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74   circumstances t
2dc10 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65  he associated me
2dc20 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72  tadata may be pr
2dc30 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61  eserved. This ma
2dc40 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f  y.** be used, fo
2dc50 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64  r example, to ad
2dc60 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72  d a regular-expr
2dc70 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20  ession matching 
2dc80 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69  scalar.** functi
2dc90 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  on. The compiled
2dca0 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
2dcb0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
2dcc0 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a  on is stored as.
2dcd0 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  ** metadata asso
2dce0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2dcf0 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64  SQL value passed
2dd00 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20   as the regular 
2dd10 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61  expression.** pa
2dd20 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70  ttern.  The comp
2dd30 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70  iled regular exp
2dd40 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72  ression can be r
2dd50 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c  eused on multipl
2dd60 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
2dd70 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
2dd80 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68  ction so that th
2dd90 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65  e original patte
2dda0 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65  rn string.** doe
2ddb0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
2ddc0 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65   recompiled on e
2ddd0 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a  ach invocation..
2dde0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2ddf0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
2de00 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2de10 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2de20 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  he metadata.** a
2de30 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65  ssociated by the
2de40 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
2de50 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20  data() function 
2de60 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67  with the Nth arg
2de70 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74  ument.** value t
2de80 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
2de90 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2dea0 6f 6e 2e 20 49 66 20 6e 6f 20 6d 65 74 61 64 61  on. If no metada
2deb0 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72  ta has been ever
2dec0 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72  .** been set for
2ded0 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
2dee0 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  t of the functio
2def0 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72  n, or if the cor
2df00 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75  responding.** fu
2df10 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
2df20 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e   has changed sin
2df30 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61  ce the meta-data
2df40 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65   was set,.** the
2df50 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  n sqlite3_get_au
2df60 78 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20  xdata() returns 
2df70 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
2df80 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2df90 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
2dfa0 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20  interface saves 
2dfb0 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
2dfc0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74  pointed to by it
2dfd0 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  s 3rd parameter 
2dfe0 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  as the metadata 
2dff0 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20  for the N-th.** 
2e000 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
2e010 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2e020 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53  ned function.  S
2e030 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
2e040 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65  ls to sqlite3_ge
2e050 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68  t_auxdata() migh
2e060 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61  t return this da
2e070 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a  ta, if it has.**
2e080 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f   not been destro
2e090 79 65 64 2e 0a 2a 2a 20 49 66 20 69 74 20 69 73  yed..** If it is
2e0a0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74   not NULL, SQLit
2e0b0 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
2e0c0 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
2e0d0 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62  function given b
2e0e0 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  y the 4th parame
2e0f0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  ter to sqlite3_s
2e100 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a  et_auxdata() on.
2e110 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  ** the metadata 
2e120 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  when the corresp
2e130 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  onding function 
2e140 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65  parameter change
2e150 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65  s.** or when the
2e160 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63   SQL statement c
2e170 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65  ompletes, whiche
2e180 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e  ver comes first.
2e190 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73  .**.** SQLite is
2e1a0 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68   free to call th
2e1b0 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64  e destructor and
2e1c0 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f   drop metadata o
2e1d0 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74  n any.** paramet
2e1e0 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69  er of any functi
2e1f0 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20  on at any time. 
2e200 20 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e   The only guaran
2e210 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74  tee is that.** t
2e220 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69  he destructor wi
2e230 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66  ll be called bef
2e240 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61  ore the metadata
2e250 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a   is dropped..**.
2e260 2a 2a 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20  ** In practice, 
2e270 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73  metadata is pres
2e280 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75  erved between fu
2e290 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72  nction calls for
2e2a0 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20  .** expressions 
2e2b0 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e  that are constan
2e2c0 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  t at compile tim
2e2d0 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73  e. This includes
2e2e0 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75   literal.** valu
2e2f0 65 73 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61  es and SQL varia
2e300 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  bles..**.** Thes
2e310 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
2e320 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
2e330 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
2e340 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53  n which.** the S
2e350 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
2e360 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e  unning..**.** IN
2e370 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2e380 7b 46 31 36 32 37 32 7d 20 54 68 65 20 5b 73 71  {F16272} The [sq
2e390 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2e3a0 61 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  a(C,N)] interfac
2e3b0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2e3c0 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
2e3d0 74 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  to metadata asso
2e3e0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2e3f0 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  Nth parameter of
2e400 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2e410 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  n.**          wh
2e420 6f 73 65 20 63 6f 6e 74 65 78 74 20 69 73 20 43  ose context is C
2e430 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  , or NULL if the
2e440 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74  re is no metadat
2e450 61 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  a associated.** 
2e460 20 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68           with th
2e470 61 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  at parameter..**
2e480 0a 2a 2a 20 7b 46 31 36 32 37 34 7d 20 54 68 65  .** {F16274} The
2e490 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
2e4a0 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20  xdata(C,N,P,D)] 
2e4b0 69 6e 74 65 72 66 61 63 65 20 61 73 73 69 67 6e  interface assign
2e4c0 73 20 61 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  s a metadata.** 
2e4d0 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72           pointer
2e4e0 20 50 20 74 6f 20 74 68 65 20 4e 74 68 20 70 61   P to the Nth pa
2e4f0 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53  rameter of the S
2e500 51 4c 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  QL function with
2e510 20 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2a 0a 2a   context C..**.*
2e520 2a 20 7b 46 31 36 32 37 36 7d 20 53 51 4c 69 74  * {F16276} SQLit
2e530 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
2e540 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77  e destructor D w
2e550 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67  ith a single arg
2e560 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20  ument.**        
2e570 20 20 77 68 69 63 68 20 69 73 20 74 68 65 20 6d    which is the m
2e580 65 74 61 64 61 74 61 20 70 6f 69 6e 74 65 72 20  etadata pointer 
2e590 50 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61  P following a ca
2e5a0 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ll to.**        
2e5b0 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61    [sqlite3_set_a
2e5c0 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d  uxdata(C,N,P,D)]
2e5d0 20 77 68 65 6e 20 53 51 4c 69 74 65 20 63 65 61   when SQLite cea
2e5e0 73 65 73 20 74 6f 20 68 6f 6c 64 0a 2a 2a 20 20  ses to hold.**  
2e5f0 20 20 20 20 20 20 20 20 74 68 65 20 6d 65 74 61          the meta
2e600 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  data..**.** {F16
2e610 32 37 37 7d 20 53 51 4c 69 74 65 20 63 65 61 73  277} SQLite ceas
2e620 65 73 20 74 6f 20 68 6f 6c 64 20 6d 65 74 61 64  es to hold metad
2e630 61 74 61 20 66 6f 72 20 61 6e 20 53 51 4c 20 66  ata for an SQL f
2e640 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
2e650 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  r.**          wh
2e660 65 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  en the value of 
2e670 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 63  that parameter c
2e680 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  hanges..**.** {F
2e690 31 36 32 37 38 7d 20 57 68 65 6e 20 5b 73 71 6c  16278} When [sql
2e6a0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2e6b0 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 73 20 69 6e  (C,N,P,D)] is in
2e6c0 76 6f 6b 65 64 2c 20 74 68 65 20 64 65 73 74 72  voked, the destr
2e6d0 75 63 74 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  uctor.**        
2e6e0 20 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20    is called for 
2e6f0 61 6e 79 20 70 72 69 6f 72 20 6d 65 74 61 64 61  any prior metada
2e700 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
2e710 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  th the same func
2e720 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
2e730 20 63 6f 6e 74 65 78 74 20 43 20 61 6e 64 20 70   context C and p
2e740 61 72 61 6d 65 74 65 72 20 4e 2e 0a 2a 2a 0a 2a  arameter N..**.*
2e750 2a 20 7b 46 31 36 32 37 39 7d 20 53 51 4c 69 74  * {F16279} SQLit
2e760 65 20 77 69 6c 6c 20 63 61 6c 6c 20 64 65 73 74  e will call dest
2e770 72 75 63 74 6f 72 73 20 66 6f 72 20 61 6e 79 20  ructors for any 
2e780 6d 65 74 61 64 61 74 61 20 69 74 20 69 73 20 68  metadata it is h
2e790 6f 6c 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  olding.**       
2e7a0 20 20 20 69 6e 20 61 20 70 61 72 74 69 63 75 6c     in a particul
2e7b0 61 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ar [prepared sta
2e7c0 74 65 6d 65 6e 74 5d 20 53 20 77 68 65 6e 20 65  tement] S when e
2e7d0 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
2e7e0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74    [sqlite3_reset
2e7f0 28 53 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  (S)] or [sqlite3
2e800 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73  _finalize(S)] is
2e810 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64   called..*/.void
2e820 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   *sqlite3_get_au
2e830 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
2e840 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  ntext*, int N);.
2e850 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
2e860 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
2e870 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
2e880 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
2e890 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a  )(void*));.../*.
2e8a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
2e8b0 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20  stants Defining 
2e8c0 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74  Special Destruct
2e8d0 6f 72 20 42 65 68 61 76 69 6f 72 20 7b 46 31 30  or Behavior {F10
2e8e0 32 38 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  280}.**.** These
2e8f0 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c   are special val
2e900 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74  ues for the dest
2e910 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70  ructor that is p
2e920 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
2e930 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e  ** final argumen
2e940 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  t to routines li
2e950 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ke [sqlite3_resu
2e960 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20  lt_blob()].  If 
2e970 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
2e980 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51  * argument is SQ
2e990 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20  LITE_STATIC, it 
2e9a0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
2e9b0 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69  ontent pointer i
2e9c0 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e  s constant.** an
2e9d0 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61  d will never cha
2e9e0 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f  nge.  It does no
2e9f0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73  t need to be des
2ea00 74 72 6f 79 65 64 2e 20 20 54 68 65 0a 2a 2a 20  troyed.  The.** 
2ea10 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
2ea20 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61   value means tha
2ea30 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69  t the content wi
2ea40 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65  ll likely change
2ea50 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20   in.** the near 
2ea60 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20  future and that 
2ea70 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61  SQLite should ma
2ea80 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ke its own priva
2ea90 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68  te copy of.** th
2eaa0 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65  e content before
2eab0 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
2eac0 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73  * The typedef is
2ead0 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f   necessary to wo
2eae0 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65  rk around proble
2eaf0 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a  ms in certain.**
2eb00 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20   C++ compilers. 
2eb10 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39   See ticket #219
2eb20 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f  1..*/.typedef vo
2eb30 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73  id (*sqlite3_des
2eb40 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f  tructor_type)(vo
2eb50 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51  id*);.#define SQ
2eb60 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20  LITE_STATIC     
2eb70 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
2eb80 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64  uctor_type)0).#d
2eb90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
2eba0 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74  NSIENT   ((sqlit
2ebb0 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
2ebc0 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  pe)-1)../*.** CA
2ebd0 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20  PI3REF: Setting 
2ebe0 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e  The Result Of An
2ebf0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 46   SQL Function {F
2ec00 31 36 34 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  16400}.**.** The
2ec10 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2ec20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
2ec30 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
2ec40 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
2ec50 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
2ec60 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
2ec70 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
2ec80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2ec90 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
2eca0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2ecb0 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
2ecc0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
2ecd0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
2ece0 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
2ecf0 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
2ed00 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65  like the [parame
2ed10 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d  ter binding] fam
2ed20 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69  ily of.** functi
2ed30 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64  ons used to bind
2ed40 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
2ed50 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
2ed60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ed70 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
2ed80 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  he [SQL paramete
2ed90 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  r] documentation
2eda0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2edb0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
2edc0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2edd0 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74  esult_blob() int
2ede0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
2edf0 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
2ee00 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
2ee10 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2ee20 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68  o be the BLOB wh
2ee30 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70  ose content is p
2ee40 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20  ointed.** to by 
2ee50 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
2ee60 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69  eter and which i
2ee70 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77  s N bytes long w
2ee80 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
2ee90 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2eea0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2eeb0 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
2eec0 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73  lob() interfaces
2eed0 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20   set the result 
2eee0 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
2eef0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2ef00 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42  nction to be a B
2ef10 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  LOB containing a
2ef20 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73  ll zero.** bytes
2ef30 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20   and N bytes in 
2ef40 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73  size, where N is
2ef50 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2ef60 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
2ef70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2ef80 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
2ef90 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
2efa0 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
2efb0 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
2efc0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2efd0 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f  tion to be a flo
2efe0 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
2eff0 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
2f000 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  y its 2nd argume
2f010 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  nt..**.** The sq
2f020 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2f030 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
2f040 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2f050 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63  ) functions.** c
2f060 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ause the impleme
2f070 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  nted SQL functio
2f080 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  n to throw an ex
2f090 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69  ception..** SQLi
2f0a0 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69  te uses the stri
2f0b0 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
2f0c0 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61   the.** 2nd para
2f0d0 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
2f0e0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
2f0f0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2f100 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61  t_error16().** a
2f110 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e  s the text of an
2f120 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
2f130 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65   SQLite interpre
2f140 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  ts the error.** 
2f150 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66  message string f
2f160 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
2f170 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54  lt_error() as UT
2f180 46 2d 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69  F-8. SQLite.** i
2f190 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74  nterprets the st
2f1a0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
2f1b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2f1c0 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  () as UTF-16 in 
2f1d0 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f  native.** byte o
2f1e0 72 64 65 72 2e 20 20 49 66 20 74 68 65 20 74 68  rder.  If the th
2f1f0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
2f200 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f210 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
2f220 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2f230 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69  or16() is negati
2f240 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
2f250 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f  akes as the erro
2f260 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c  r.** message all
2f270 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68   text up through
2f280 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
2f290 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66  character..** If
2f2a0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
2f2b0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2f2c0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
2f2d0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
2f2e0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
2f2f0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68   non-negative th
2f300 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
2f310 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74  that many.** byt
2f320 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
2f330 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  rs) from the 2nd
2f340 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
2f350 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
2f360 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2f370 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
2f380 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
2f390 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72  t_error16().** r
2f3a0 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70  outines make a p
2f3b0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
2f3c0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
2f3d0 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20   text before.** 
2f3e0 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65  they return.  He
2f3f0 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  nce, the calling
2f400 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65   function can de
2f410 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d  allocate or.** m
2f420 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61  odify the text a
2f430 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e  fter they return
2f440 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
2f450 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
2f460 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
2f470 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67  ) function chang
2f480 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  es the error cod
2f490 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
2f4a0 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73   SQLite as a res
2f4b0 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ult of an error 
2f4c0 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20  in a function.  
2f4d0 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74  By default,.** t
2f4e0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  he error code is
2f4f0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
2f500 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
2f510 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
2f520 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
2f530 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2f540 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
2f550 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
2f560 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
2f570 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2f580 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69  te3_result_toobi
2f590 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  g() interface ca
2f5a0 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
2f5b0 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a  hrow an error.**
2f5c0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
2f5d0 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
2f5e0 42 20 69 73 20 74 6f 20 6c 6f 6e 67 20 74 6f 20  B is to long to 
2f5f0 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
2f600 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2f610 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ult_nomem() inte
2f620 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
2f630 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
2f640 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
2f650 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
2f660 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
2f670 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  led..**.** The s
2f680 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
2f690 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  t() interface se
2f6a0 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
2f6b0 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
2f6c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2f6d0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2f6e0 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e   the 32-bit sign
2f6f0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
2f700 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
2f710 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
2f720 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
2f730 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
2f740 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
2f750 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
2f760 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2f770 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2f780 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
2f790 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2f7a0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
2f7b0 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
2f7c0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
2f7d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2f7e0 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  _null() interfac
2f7f0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
2f800 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
2f810 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2f820 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2f830 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  o be NULL..**.**
2f840 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2f850 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  ult_text(), sqli
2f860 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2f870 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  6(),.** sqlite3_
2f880 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
2f890 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
2f8a0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29  esult_text16be()
2f8b0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73   interfaces.** s
2f8c0 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  et the return va
2f8d0 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  lue of the appli
2f8e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2f8f0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  unction to be.**
2f900 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77   a text string w
2f910 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e  hich is represen
2f920 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54  ted as UTF-8, UT
2f930 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
2f940 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31   order,.** UTF-1
2f950 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c  6 little endian,
2f960 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65   or UTF-16 big e
2f970 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
2f980 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74  ely..** SQLite t
2f990 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65  akes the text re
2f9a0 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70  sult from the ap
2f9b0 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a  plication from.*
2f9c0 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  * the 2nd parame
2f9d0 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ter of the sqlit
2f9e0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2f9f0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49  interfaces..** I
2fa00 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
2fa10 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2fa20 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2fa30 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
2fa40 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
2fa50 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73  SQLite takes res
2fa60 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68  ult text from th
2fa70 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  e 2nd parameter.
2fa80 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  ** through the f
2fa90 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
2faa0 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33  ter..** If the 3
2fab0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2fac0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2fad0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2fae0 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65  ces.** is non-ne
2faf0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20  gative, then as 
2fb00 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20  many bytes (not 
2fb10 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74  characters) of t
2fb20 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74  he text.** point
2fb30 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64  ed to by the 2nd
2fb40 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74   parameter are t
2fb50 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c  aken as the appl
2fb60 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a  ication-defined.
2fb70 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75  ** function resu
2fb80 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74  lt..** If the 4t
2fb90 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
2fba0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2fbb0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
2fbc0 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
2fbd0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
2fbe0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
2fbf0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
2fc00 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
2fc10 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
2fc20 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
2fc30 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
2fc40 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
2fc50 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
2fc60 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
2fc70 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72  * If the 4th par
2fc80 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
2fc90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2fca0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72  t* interfaces or
2fcb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
2fcc0 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
2fcd0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
2fce0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
2fcf0 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73  hen SQLite.** as
2fd00 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
2fd10 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
2fd20 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e  lt is in constan
2fd30 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  t space and does
2fd40 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65   not.** copy the
2fd50 20 69 74 20 6f 72 20 63 61 6c 6c 20 61 20 64 65   it or call a de
2fd60 73 74 72 75 63 74 6f 72 20 77 68 65 6e 20 69 74  structor when it
2fd70 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
2fd80 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
2fd90 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70  .** If the 4th p
2fda0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2fdb0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2fdc0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
2fdd0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
2fde0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
2fdf0 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
2fe00 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
2fe10 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
2fe20 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
2fe30 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
2fe40 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
2fe50 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
2fe60 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
2fe70 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
2fe80 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ns..**.** The sq
2fe90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2fea0 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ue() interface s
2feb0 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ets the result o
2fec0 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
2fed0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2fee0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f  ction to be a co
2fef0 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f  py the.** [unpro
2ff00 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2ff10 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65  alue] object spe
2ff20 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e  cified by the 2n
2ff30 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
2ff40 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  e.** sqlite3_res
2ff50 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
2ff60 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
2ff70 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
2ff80 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20  e3_value].** so 
2ff90 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
2ffa0 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
2ffb0 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
2ffc0 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
2ffd0 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
2ffe0 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
2fff0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
30000 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
30010 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f   harm..** A [pro
30020 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
30030 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79  alue] object may
30040 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20   always be used 
30050 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70  where an.** [unp
30060 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
30070 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69  _value] object i
30080 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65  s required, so e
30090 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66  ither.** kind of
300a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
300b0 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75   object can be u
300c0 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e  sed with this in
300d0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  terface..**.** I
300e0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
300f0 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
30100 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66   within the diff
30110 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20  erent thread.** 
30120 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e  than the one con
30130 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c  taining the appl
30140 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
30150 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65  function that re
30160 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73  ceived.** the [s
30170 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
30180 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73  pointer, the res
30190 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
301a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
301b0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ANTS:.**.** {F16
301c0 34 30 33 7d 20 54 68 65 20 64 65 66 61 75 6c 74  403} The default
301d0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
301e0 6f 6d 20 61 6e 79 20 53 51 4c 20 66 75 6e 63 74  om any SQL funct
301f0 69 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ion is NULL..**.
30200 2a 2a 20 7b 46 31 36 34 30 36 7d 20 54 68 65 20  ** {F16406} The 
30210 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
30220 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  blob(C,V,N,D)] i
30230 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
30240 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
30250 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
30260 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
30270 65 20 61 20 42 4c 4f 42 20 74 68 61 74 20 69 73  e a BLOB that is
30280 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20   N bytes.**     
30290 20 20 20 20 20 69 6e 20 6c 65 6e 67 74 68 20 61       in length a
302a0 6e 64 20 77 69 74 68 20 63 6f 6e 74 65 6e 74 20  nd with content 
302b0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2e  pointed to by V.
302c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 30 39 7d 20  .**.** {F16409} 
302d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
302e0 75 6c 74 5f 64 6f 75 62 6c 65 28 43 2c 56 29 5d  ult_double(C,V)]
302f0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
30300 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
30310 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
30320 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
30330 20 62 65 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   be the floating
30340 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 56 2e 0a   point value V..
30350 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31 32 7d 20 54  **.** {F16412} T
30360 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
30370 6c 74 5f 65 72 72 6f 72 28 43 2c 56 2c 4e 29 5d  lt_error(C,V,N)]
30380 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
30390 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a  es the return.**
303a0 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
303b0 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
303c0 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e   be an exception
303d0 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65   with error code
303e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
303f0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20  LITE_ERROR] and 
30400 61 20 55 54 46 2d 38 20 65 72 72 6f 72 20 6d 65  a UTF-8 error me
30410 73 73 61 67 65 20 63 6f 70 69 65 64 20 66 72 6f  ssage copied fro
30420 6d 20 56 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  m V up to the.**
30430 20 20 20 20 20 20 20 20 20 20 66 69 72 73 74 20            first 
30440 7a 65 72 6f 20 62 79 74 65 20 6f 72 20 75 6e 74  zero byte or unt
30450 69 6c 20 4e 20 62 79 74 65 73 20 61 72 65 20 72  il N bytes are r
30460 65 61 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69  ead if N is posi
30470 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  tive..**.** {F16
30480 34 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  415} The [sqlite
30490 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
304a0 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61  (C,V,N)] interfa
304b0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
304c0 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
304d0 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74    value of funct
304e0 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65  ion C to be an e
304f0 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72  xception with er
30500 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20  ror code.**     
30510 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52       [SQLITE_ERR
30520 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 2d 31 36  OR] and a UTF-16
30530 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
30540 65 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  er error message
30550 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 70  .**          cop
30560 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f  ied from V up to
30570 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
30580 74 65 72 6d 69 6e 61 74 6f 72 20 6f 72 20 75 6e  terminator or un
30590 74 69 6c 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20  til N bytes.**  
305a0 20 20 20 20 20 20 20 20 61 72 65 20 72 65 61 64          are read
305b0 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76   if N is positiv
305c0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 31 38  e..**.** {F16418
305d0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
305e0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
305f0 69 67 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  ig(C)] interface
30600 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
30610 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
30620 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e  value of the fun
30630 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
30640 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
30650 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20  error code.**   
30660 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54         [SQLITE_T
30670 4f 4f 42 49 47 5d 20 61 6e 64 20 61 6e 20 61 70  OOBIG] and an ap
30680 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20  propriate error 
30690 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b  message..**.** {
306a0 46 31 36 34 32 31 7d 20 54 68 65 20 5b 73 71 6c  F16421} The [sql
306b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
306c0 72 5f 6e 6f 6d 65 6d 28 43 29 5d 20 69 6e 74 65  r_nomem(C)] inte
306d0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
306e0 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
306f0 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68       value of th
30700 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  e function C to 
30710 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
30720 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a  with error code.
30730 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
30740 49 54 45 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20 61  ITE_NOMEM] and a
30750 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72  n appropriate er
30760 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
30770 2a 2a 20 7b 46 31 36 34 32 34 7d 20 54 68 65 20  ** {F16424} The 
30780 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
30790 65 72 72 6f 72 5f 63 6f 64 65 28 43 2c 45 29 5d  error_code(C,E)]
307a0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
307b0 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a  es the return.**
307c0 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
307d0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
307e0 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70  C to be an excep
307f0 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20  tion with error 
30800 63 6f 64 65 20 45 2e 0a 2a 2a 20 20 20 20 20 20  code E..**      
30810 20 20 20 20 54 68 65 20 65 72 72 6f 72 20 6d 65      The error me
30820 73 73 61 67 65 20 74 65 78 74 20 69 73 20 75 6e  ssage text is un
30830 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  changed..**.** {
30840 46 31 36 34 32 37 7d 20 54 68 65 20 5b 73 71 6c  F16427} The [sql
30850 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
30860 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,V)] interface 
30870 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
30880 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
30890 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
308a0 20 43 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d   C to be the 32-
308b0 62 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75  bit integer valu
308c0 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34  e V..**.** {F164
308d0 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  30} The [sqlite3
308e0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 43 2c  _result_int64(C,
308f0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  V)] interface ch
30900 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
30910 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
30920 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
30930 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
30940 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20  t integer value 
30950 56 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 33  V..**.** {F16433
30960 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
30970 65 73 75 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20 69  esult_null(C)] i
30980 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
30990 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
309a0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
309b0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
309c0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46  e NULL..**.** {F
309d0 31 36 34 33 36 7d 20 54 68 65 20 5b 73 71 6c 69  16436} The [sqli
309e0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
309f0 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
30a00 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
30a10 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
30a20 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
30a30 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
30a40 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
30a50 20 20 20 20 20 20 20 20 20 20 56 20 75 70 20 74            V up t
30a60 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
30a70 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76   if N is negativ
30a80 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  e.**          or
30a90 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74   the first N byt
30aa0 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20  es of V if N is 
30ab0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a  non-negative..**
30ac0 0a 2a 2a 20 7b 46 31 36 34 33 39 7d 20 54 68 65  .** {F16439} The
30ad0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
30ae0 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29  _text16(C,V,N,D)
30af0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
30b00 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
30b10 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
30b20 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
30b30 6f 20 62 65 20 74 68 65 20 55 54 46 2d 31 36 20  o be the UTF-16 
30b40 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
30b50 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  r.**          st
30b60 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65  ring V up to the
30b70 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e   first zero if N
30b80 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20   is negative.** 
30b90 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
30ba0 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66  first N bytes of
30bb0 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e   V if N is non-n
30bc0 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
30bd0 46 31 36 34 34 32 7d 20 54 68 65 20 5b 73 71 6c  F16442} The [sql
30be0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
30bf0 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  16be(C,V,N,D)] i
30c00 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
30c10 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
30c20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
30c30 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
30c40 65 20 74 68 65 20 55 54 46 2d 31 36 20 62 69 67  e the UTF-16 big
30c50 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20  -endian.**      
30c60 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20      string V up 
30c70 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
30c80 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69  o if N is negati
30c90 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ve.**          o
30ca0 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79  r the first N by
30cb0 74 65 73 20 6f 72 20 56 20 69 66 20 4e 20 69 73  tes or V if N is
30cc0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a   non-negative..*
30cd0 2a 0a 2a 2a 20 7b 46 31 36 34 34 35 7d 20 54 68  *.** {F16445} Th
30ce0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
30cf0 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e  t_text16le(C,V,N
30d00 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
30d10 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
30d20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
30d30 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
30d40 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d  C to be the UTF-
30d50 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  16 little-endian
30d60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
30d70 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65 20  ing V up to the 
30d80 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20  first zero if N 
30d90 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20  is negative.**  
30da0 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66          or the f
30db0 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20  irst N bytes of 
30dc0 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65  V if N is non-ne
30dd0 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  gative..**.** {F
30de0 31 36 34 34 38 7d 20 54 68 65 20 5b 73 71 6c 69  16448} The [sqli
30df0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
30e00 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,V)] interface
30e10 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
30e20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
30e30 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
30e40 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 5b 75  n C to be the [u
30e50 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
30e60 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 20 20 20  e3_value].**    
30e70 20 20 20 20 20 20 6f 62 6a 65 63 74 20 56 2e 0a        object V..
30e80 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 31 7d 20 54  **.** {F16451} 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 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29  lt_zeroblob(C,N)
30eb0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
30ec0 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
30ed0 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
30ee0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
30ef0 6f 20 62 65 20 61 6e 20 4e 2d 62 79 74 65 20 42  o be an N-byte B
30f00 4c 4f 42 20 6f 66 20 61 6c 6c 20 7a 65 72 6f 73  LOB of all zeros
30f10 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 35 34 7d  ..**.** {F16454}
30f20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
30f30 73 75 6c 74 5f 65 72 72 6f 72 28 29 5d 20 61 6e  sult_error()] an
30f40 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
30f50 74 5f 65 72 72 6f 72 31 36 28 29 5d 0a 2a 2a 20  t_error16()].** 
30f60 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
30f70 63 65 73 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  ces make a copy 
30f80 6f 66 20 74 68 65 69 72 20 65 72 72 6f 72 20 6d  of their error m
30f90 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 62  essage strings b
30fa0 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20  efore.**        
30fb0 20 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a    returning..**.
30fc0 2a 2a 20 7b 46 31 36 34 35 37 7d 20 49 66 20 74  ** {F16457} If t
30fd0 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20  he D destructor 
30fe0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
30ff0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
31000 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  b(C,V,N,D)],.** 
31010 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
31020 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c  3_result_text(C,
31030 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65  V,N,D)], [sqlite
31040 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
31050 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
31060 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
31070 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
31080 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  C,V,N,D)], or.**
31090 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
310a0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
310b0 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20  le(C,V,N,D)] is 
310c0 74 68 65 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51  the constant [SQ
310d0 4c 49 54 45 5f 53 54 41 54 49 43 5d 0a 2a 2a 20  LITE_STATIC].** 
310e0 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 6e 6f           then no
310f0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 65   destructor is e
31100 76 65 72 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68  ver called on th
31110 65 20 70 6f 69 6e 74 65 72 20 56 20 61 6e 64 20  e pointer V and 
31120 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20 20  SQLite.**       
31130 20 20 20 61 73 73 75 6d 65 73 20 74 68 61 74 20     assumes that 
31140 56 20 69 73 20 69 6d 6d 75 74 61 62 6c 65 2e 0a  V is immutable..
31150 2a 2a 0a 2a 2a 20 7b 46 31 36 34 36 30 7d 20 49  **.** {F16460} I
31160 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74  f the D destruct
31170 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  or parameter to 
31180 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
31190 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a  blob(C,V,N,D)],.
311a0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
311b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
311c0 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c  (C,V,N,D)], [sql
311d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
311e0 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  16(C,V,N,D)],.**
311f0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
31200 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
31210 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72  be(C,V,N,D)], or
31220 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
31230 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
31240 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20  t16le(C,V,N,D)] 
31250 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 0a  is the constant.
31260 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
31270 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74  ITE_TRANSIENT] t
31280 68 65 6e 20 74 68 65 20 69 6e 74 65 72 66 61 63  hen the interfac
31290 65 73 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  es makes a copy 
312a0 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
312b0 20 20 20 63 6f 6e 74 65 6e 74 20 6f 66 20 56 20     content of V 
312c0 61 6e 64 20 72 65 74 61 69 6e 73 20 74 68 65 20  and retains the 
312d0 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  copy..**.** {F16
312e0 34 36 33 7d 20 49 66 20 74 68 65 20 44 20 64 65  463} If the D de
312f0 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74  structor paramet
31300 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  er to [sqlite3_r
31310 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
31320 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
31330 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
31340 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d  t_text(C,V,N,D)]
31350 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  , [sqlite3_resul
31360 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
31370 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
31380 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
31390 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
313a0 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
313b0 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
313c0 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c  lt_text16le(C,V,
313d0 4e 2c 44 29 5d 20 69 73 20 73 6f 6d 65 20 76 61  N,D)] is some va
313e0 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a  lue other than.*
313f0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63  *          the c
31400 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45  onstants [SQLITE
31410 5f 53 54 41 54 49 43 5d 20 61 6e 64 20 5b 53 51  _STATIC] and [SQ
31420 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20  LITE_TRANSIENT] 
31430 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
31440 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
31450 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
31460 6f 72 20 44 20 77 69 74 68 20 56 20 61 73 20 69  or D with V as i
31470 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  ts only argument
31480 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65  .**          whe
31490 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  n it has finishe
314a0 64 20 77 69 74 68 20 74 68 65 20 56 20 76 61 6c  d with the V val
314b0 75 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ue..*/.void sqli
314c0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
314d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
314e0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
314f0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
31500 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
31510 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
31520 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31530 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20  , double);.void 
31540 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31550 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e  rror(sqlite3_con
31560 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
31570 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  r*, int);.void s
31580 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31590 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ror16(sqlite3_co
315a0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
315b0 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
315c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
315d0 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69  rror_toobig(sqli
315e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
315f0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
31600 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73  lt_error_nomem(s
31610 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
31620 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
31630 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
31640 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31650 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
31660 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
31670 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31680 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
31690 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
316a0 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
316b0 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  xt*, sqlite3_int
316c0 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  64);.void sqlite
316d0 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71  3_result_null(sq
316e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
316f0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
31700 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65  sult_text(sqlite
31710 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
31720 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f  t char*, int, vo
31730 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
31740 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
31750 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  lt_text16(sqlite
31760 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
31770 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
31780 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
31790 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
317a0 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  lt_text16le(sqli
317b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
317c0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
317d0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
317e0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
317f0 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c  ult_text16be(sql
31800 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
31810 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
31820 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
31830 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
31840 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74  sult_value(sqlit
31850 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
31860 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f  ite3_value*);.vo
31870 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
31880 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  t_zeroblob(sqlit
31890 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
318a0 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
318b0 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77  3REF: Define New
318c0 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65   Collating Seque
318d0 6e 63 65 73 20 7b 46 31 36 36 30 30 7d 0a 2a 2a  nces {F16600}.**
318e0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
318f0 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20  ons are used to 
31900 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  add new collatio
31910 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74  n sequences to t
31920 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
31930 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
31940 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
31950 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
31960 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** The name of t
31970 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e  he new collation
31980 20 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 65   sequence is spe
31990 63 69 66 69 65 64 20 61 73 20 61 20 55 54 46 2d  cified as a UTF-
319a0 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20  8 string.** for 
319b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
319c0 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73  ollation() and s
319d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
319e0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20  llation_v2().** 
319f0 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72  and a UTF-16 str
31a00 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ing for sqlite3_
31a10 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
31a20 31 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61 73  16(). In all cas
31a30 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69  es.** the name i
31a40 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
31a50 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
31a60 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
31a70 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
31a80 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nt may be one of
31a90 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b   the constants [
31aa0 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a  SQLITE_UTF8],.**
31ab0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
31ac0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  ] or [SQLITE_UTF
31ad0 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16BE], indicatin
31ae0 67 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d  g that the user-
31af0 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74  supplied.** rout
31b00 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62  ine expects to b
31b10 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72  e passed pointer
31b20 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63  s to strings enc
31b30 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
31b40 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74  ,.** UTF-16 litt
31b50 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54  le-endian, or UT
31b60 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c  F-16 big-endian,
31b70 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 54   respectively. T
31b80 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75  he.** third argu
31b90 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f 20  ment might also 
31ba0 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  be [SQLITE_UTF16
31bb0 5f 41 4c 49 47 4e 45 44 5d 20 74 6f 20 69 6e 64  _ALIGNED] to ind
31bc0 69 63 61 74 65 20 74 68 61 74 0a 2a 2a 20 74 68  icate that.** th
31bd0 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74  e routine expect
31be0 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36  s pointers to 16
31bf0 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65  -bit word aligne
31c00 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20  d strings.** of 
31c10 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
31c20 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
31c30 6f 66 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70  of the host comp
31c40 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f  uter..**.** A po
31c50 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 65  inter to the use
31c60 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69  r supplied routi
31c70 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  ne must be passe
31c80 64 20 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a  d as the fifth.*
31c90 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20  * argument.  If 
31ca0 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73  it is NULL, this
31cb0 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
31cc0 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c  deleting the col
31cd0 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
31ce0 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69  ce (so that SQLi
31cf0 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69  te cannot call i
31d00 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45  t anymore)..** E
31d10 61 63 68 20 74 69 6d 65 20 74 68 65 20 61 70 70  ach time the app
31d20 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69 65  lication supplie
31d30 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e  d function is in
31d40 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73  voked, it is pas
31d50 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66 69  sed.** as its fi
31d60 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 61 20  rst parameter a 
31d70 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
31d80 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  * passed as the 
31d90 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a  fourth argument.
31da0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  ** to sqlite3_cr
31db0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
31dc0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61   or sqlite3_crea
31dd0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
31de0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61  ..**.** The rema
31df0 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20  ining arguments 
31e00 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
31e10 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74  on-supplied rout
31e20 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72 69  ine are two stri
31e30 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70  ngs,.** each rep
31e40 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c  resented by a (l
31e50 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61 69  ength, data) pai
31e60 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e  r and encoded in
31e70 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a   the encoding.**
31e80 20 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64   that was passed
31e90 20 61 73 20 74 68 65 20 74 68 69 72 64 20 61 72   as the third ar
31ea0 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20  gument when the 
31eb0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
31ec0 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74  ce was.** regist
31ed0 65 72 65 64 2e 20 7b 45 4e 44 7d 20 54 68 65 20  ered. {END} The 
31ee0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
31ef0 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f  ned collation ro
31f00 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20  utine should.** 
31f10 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c  return negative,
31f20 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76   zero or positiv
31f30 65 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73  e if the first s
31f40 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68  tring is less th
31f50 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c  an,.** equal to,
31f60 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
31f70 20 74 68 65 20 73 65 63 6f 6e 64 20 73 74 72 69   the second stri
31f80 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e 47  ng. i.e. (STRING
31f90 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a  1 - STRING2)..**
31fa0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
31fb0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
31fc0 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65  _v2() works like
31fd0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
31fe0 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65  collation().** e
31ff0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 74 61  xcept that it ta
32000 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61 72 67  kes an extra arg
32010 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
32020 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a   destructor for.
32030 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  ** the collation
32040 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  .  The destructo
32050 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e  r is called when
32060 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
32070 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61  s.** destroyed a
32080 6e 64 20 69 73 20 70 61 73 73 65 64 20 61 20 63  nd is passed a c
32090 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74  opy of the fourt
320a0 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64  h parameter void
320b0 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20  * pointer.** of 
320c0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  the sqlite3_crea
320d0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
320e0 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73  )..** Collations
320f0 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20 77   are destroyed w
32100 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65  hen they are ove
32110 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
32120 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
32130 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
32140 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ion functions or
32150 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74 61 62   when the [datab
32160 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
32170 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69  is closed.** usi
32180 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
32190 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  e()]..**.** INVA
321a0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
321b0 31 36 36 30 33 7d 20 41 20 73 75 63 63 65 73 73  16603} A success
321c0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a  ful call to the.
321d0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
321e0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
321f0 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
32200 2c 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,D)] interface
32210 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
32220 69 73 74 65 72 73 20 66 75 6e 63 74 69 6f 6e 20  isters function 
32230 46 20 61 73 20 74 68 65 20 63 6f 6d 70 61 72 69  F as the compari
32240 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 75 73 65  son function use
32250 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  d to.**         
32260 20 69 6d 70 6c 65 6d 65 6e 74 20 63 6f 6c 6c 61   implement colla
32270 74 69 6f 6e 20 58 20 6f 6e 20 74 68 65 20 5b 64  tion X on the [d
32280 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32290 6f 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20 20 20 20  on] B for.**    
322a0 20 20 20 20 20 20 64 61 74 61 62 61 73 65 73 20        databases 
322b0 68 61 76 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20  having encoding 
322c0 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 34  E..**.** {F16604
322d0 7d 20 53 51 4c 69 74 65 20 75 6e 64 65 72 73 74  } SQLite underst
322e0 61 6e 64 73 20 74 68 65 20 58 20 70 61 72 61 6d  ands the X param
322f0 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  eter to.**      
32300 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65      [sqlite3_cre
32310 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
32320 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 61  (B,X,E,P,F,D)] a
32330 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
32340 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
32350 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 20  UTF-8 string in 
32360 77 68 69 63 68 20 63 61 73 65 20 69 73 20 69 67  which case is ig
32370 6e 6f 72 65 64 20 66 6f 72 20 41 53 43 49 49 20  nored for ASCII 
32380 63 68 61 72 61 63 74 65 72 73 20 61 6e 64 0a 2a  characters and.*
32390 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 73 69  *          is si
323a0 67 6e 69 66 69 63 61 6e 74 20 66 6f 72 20 6e 6f  gnificant for no
323b0 6e 2d 41 53 43 49 49 20 63 68 61 72 61 63 74 65  n-ASCII characte
323c0 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30  rs..**.** {F1660
323d0 36 7d 20 53 75 63 63 65 73 73 69 76 65 20 63 61  6} Successive ca
323e0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
323f0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
32400 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
32410 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  ].**          wi
32420 74 68 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  th the same valu
32430 65 73 20 66 6f 72 20 42 2c 20 58 2c 20 61 6e 64  es for B, X, and
32440 20 45 2c 20 6f 76 65 72 72 69 64 65 20 70 72 69   E, override pri
32450 6f 72 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20  or values.**    
32460 20 20 20 20 20 20 6f 66 20 50 2c 20 46 2c 20 61        of P, F, a
32470 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  nd D..**.** {F16
32480 36 30 39 7d 20 49 66 20 74 68 65 20 64 65 73 74  609} If the dest
32490 72 75 63 74 6f 72 20 44 20 69 6e 20 5b 73 71 6c  ructor D in [sql
324a0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
324b0 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
324c0 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,F,D)].**       
324d0 20 20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74     is not NULL t
324e0 68 65 6e 20 69 74 20 69 73 20 63 61 6c 6c 65 64  hen it is called
324f0 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50   with argument P
32500 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20   when the.**    
32510 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20        collating 
32520 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70  function is drop
32530 70 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ped by SQLite..*
32540 2a 0a 2a 2a 20 7b 46 31 36 36 31 32 7d 20 41 20  *.** {F16612} A 
32550 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
32560 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77 68  on is dropped wh
32570 65 6e 20 69 74 20 69 73 20 6f 76 65 72 6c 6f 61  en it is overloa
32580 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36  ded..**.** {F166
32590 31 35 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20  15} A collating 
325a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70  function is drop
325b0 70 65 64 20 77 68 65 6e 20 74 68 65 20 64 61 74  ped when the dat
325c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
325d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
325e0 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71  closed using [sq
325f0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
32600 2a 2a 0a 2a 2a 20 7b 46 31 36 36 31 38 7d 20 54  **.** {F16618} T
32610 68 65 20 70 6f 69 6e 74 65 72 20 50 20 69 6e 20  he pointer P in 
32620 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32630 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58  collation_v2(B,X
32640 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20  ,E,P,F,D)].**   
32650 20 20 20 20 20 20 20 69 73 20 70 61 73 73 65 64         is passed
32660 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
32670 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
32680 74 6f 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f  to the compariso
32690 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75  n.**          fu
326a0 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c  nction F for all
326b0 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
326c0 63 61 74 69 6f 6e 73 20 6f 66 20 46 2e 0a 2a 2a  cations of F..**
326d0 0a 2a 2a 20 7b 46 31 36 36 32 31 7d 20 41 20 63  .** {F16621} A c
326e0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
326f0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
32700 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 69 73 20  (B,X,E,P,F)] is 
32710 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20  exactly.**      
32720 20 20 20 20 74 68 65 20 73 61 6d 65 20 61 73 20      the same as 
32730 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
32740 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
32750 69 6f 6e 5f 76 32 28 29 5d 20 77 69 74 68 0a 2a  ion_v2()] with.*
32760 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
32770 61 6d 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  ame parameters a
32780 6e 64 20 61 20 4e 55 4c 4c 20 64 65 73 74 72 75  nd a NULL destru
32790 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ctor..**.** {F16
327a0 36 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e 67 20 61  624} Following a
327b0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
327c0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
327d0 58 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a 2a 2a 20  X,E,P,F,D)],.** 
327e0 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20           SQLite 
327f0 75 73 65 73 20 74 68 65 20 63 6f 6d 70 61 72 69  uses the compari
32800 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 46 20 66  son function F f
32810 6f 72 20 61 6c 6c 20 74 65 78 74 20 63 6f 6d 70  or all text comp
32820 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  arison.**       
32830 20 20 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e     operations on
32840 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
32850 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 6f 6e 20  onnection] B on 
32860 74 65 78 74 20 76 61 6c 75 65 73 20 74 68 61 74  text values that
32870 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 65  .**          use
32880 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 73   the collating s
32890 65 71 75 65 6e 63 65 20 6e 61 6d 65 64 20 58 2e  equence named X.
328a0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 32 37 7d 20  .**.** {F16627} 
328b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
328c0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
328d0 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 77 6f 72 6b  B,X,E,P,F)] work
328e0 73 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  s the same.**   
328f0 20 20 20 20 20 20 20 61 73 20 5b 73 71 6c 69 74         as [sqlit
32900 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
32910 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20  ion(B,X,E,P,F)] 
32920 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 0a  except that the.
32930 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c  **          coll
32940 61 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73 20  ation name X is 
32950 75 6e 64 65 72 73 74 6f 6f 64 20 61 73 20 55 54  understood as UT
32960 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62  F-16 in native b
32970 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20  yte order.**    
32980 20 20 20 20 20 20 69 6e 73 74 65 61 64 20 6f 66        instead of
32990 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46   UTF-8..**.** {F
329a0 31 36 36 33 30 7d 20 57 68 65 6e 20 6d 75 6c 74  16630} When mult
329b0 69 70 6c 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20  iple comparison 
329c0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 76  functions are av
329d0 61 69 6c 61 62 6c 65 20 66 6f 72 20 74 68 65 20  ailable for the 
329e0 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
329f0 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65   collating seque
32a00 6e 63 65 2c 20 53 51 4c 69 74 65 20 63 68 6f 6f  nce, SQLite choo
32a10 73 65 73 20 74 68 65 20 6f 6e 65 20 77 68 6f 73  ses the one whos
32a20 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  e text encoding.
32a30 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 71 75  **          requ
32a40 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  ires the least a
32a50 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 76 65 72 73  mount of convers
32a60 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20 64 65 66  ion from the def
32a70 61 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ault.**         
32a80 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f   text encoding o
32a90 66 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a  f the database..
32aa0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
32ab0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
32ac0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
32ad0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
32ae0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
32af0 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
32b00 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
32b10 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
32b20 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
32b30 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
32b40 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
32b50 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ation_v2(.  sqli
32b60 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
32b70 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
32b80 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
32b90 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43  void*,.  int(*xC
32ba0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
32bb0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
32bc0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a  t,const void*),.
32bd0 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
32be0 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  )(void*).);.int 
32bf0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
32c00 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71  ollation16(.  sq
32c10 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
32c20 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
32c30 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
32c40 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
32c50 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
32c60 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
32c70 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
32c80 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
32c90 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e  REF: Collation N
32ca0 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 20  eeded Callbacks 
32cb0 7b 46 31 36 37 30 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F16700}.**.** T
32cc0 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74  o avoid having t
32cd0 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63  o register all c
32ce0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
32cf0 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61  es before a data
32d00 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75  base.** can be u
32d10 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61  sed, a single ca
32d20 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
32d30 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
32d40 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 64 61  d with the.** da
32d50 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 6f  tabase handle to
32d60 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65   be called whene
32d70 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64  ver an undefined
32d80 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
32d90 6e 63 65 20 69 73 0a 2a 2a 20 72 65 71 75 69 72  nce is.** requir
32da0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ed..**.** If the
32db0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67   function is reg
32dc0 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
32dd0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  e sqlite3_collat
32de0 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49  ion_needed() API
32df0 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
32e00 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73  passed the names
32e10 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   of undefined co
32e20 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
32e30 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20  s as strings.** 
32e40 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38  encoded in UTF-8
32e50 2e 20 7b 46 31 36 37 30 33 7d 20 49 66 20 73 71  . {F16703} If sq
32e60 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
32e70 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73  needed16() is us
32e80 65 64 2c 20 74 68 65 20 6e 61 6d 65 73 0a 2a 2a  ed, the names.**
32e90 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55   are passed as U
32ea0 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65  TF-16 in machine
32eb0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
32ec0 65 72 2e 20 41 20 63 61 6c 6c 20 74 6f 20 65 69  er. A call to ei
32ed0 74 68 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ther.** function
32ee0 20 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78   replaces any ex
32ef0 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e  isting callback.
32f00 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
32f10 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
32f20 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61  ked, the first a
32f30 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
32f40 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
32f50 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
32f60 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
32f70 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
32f80 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
32f90 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
32fa0 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  6().  The second
32fb0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
32fc0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 68 61 6e   database.** han
32fd0 64 6c 65 2e 20 20 54 68 65 20 74 68 69 72 64 20  dle.  The third 
32fe0 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
32ff0 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  of [SQLITE_UTF8]
33000 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  ,.** [SQLITE_UTF
33010 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  16BE], or [SQLIT
33020 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69  E_UTF16LE], indi
33030 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 0a  cating the most.
33040 2a 2a 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72  ** desirable for
33050 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  m of the collati
33060 6f 6e 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63  on sequence func
33070 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 0a 2a  tion required..*
33080 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  * The fourth par
33090 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
330a0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71  me of the.** req
330b0 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  uired collation 
330c0 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20  sequence..**.** 
330d0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
330e0 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67  ction should reg
330f0 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65  ister the desire
33100 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e  d collation usin
33110 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
33120 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
33130 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
33140 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
33150 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
33160 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33170 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  on_v2()]..**.** 
33180 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
33190 2a 20 7b 46 31 36 37 30 32 7d 20 41 20 73 75 63  * {F16702} A suc
331a0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
331b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
331c0 6f 6e 5f 6e 65 65 64 65 64 28 44 2c 50 2c 46 29  on_needed(D,P,F)
331d0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
331e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
331f0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 44 2c 50  ion_needed16(D,P
33200 2c 46 29 5d 20 63 61 75 73 65 73 0a 2a 2a 20 20  ,F)] causes.**  
33210 20 20 20 20 20 20 20 20 74 68 65 20 5b 64 61 74          the [dat
33220 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
33230 5d 20 44 20 74 6f 20 69 6e 76 6f 6b 65 20 63 61  ] D to invoke ca
33240 6c 6c 62 61 63 6b 20 46 20 77 69 74 68 20 66 69  llback F with fi
33250 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rst.**          
33260 70 61 72 61 6d 65 74 65 72 20 50 20 77 68 65 6e  parameter P when
33270 65 76 65 72 20 69 74 20 6e 65 65 64 73 20 61 20  ever it needs a 
33280 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
33290 69 6f 6e 20 66 6f 72 20 61 0a 2a 2a 20 20 20 20  ion for a.**    
332a0 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20        collating 
332b0 73 65 71 75 65 6e 63 65 20 74 68 61 74 20 69 74  sequence that it
332c0 20 64 6f 65 73 20 6e 6f 74 20 6b 6e 6f 77 20 61   does not know a
332d0 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  bout..**.** {F16
332e0 37 30 34 7d 20 45 61 63 68 20 73 75 63 63 65 73  704} Each succes
332f0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
33300 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
33310 6e 65 65 64 65 64 28 29 5d 20 6f 72 0a 2a 2a 20  needed()] or.** 
33320 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
33330 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
33340 65 64 31 36 28 29 5d 20 6f 76 65 72 72 69 64 65  ed16()] override
33350 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  s the callback r
33360 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20  egistered.**    
33370 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d        on the sam
33380 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
33390 65 63 74 69 6f 6e 5d 20 62 79 20 70 72 69 6f 72  ection] by prior
333a0 20 63 61 6c 6c 73 20 74 6f 20 65 69 74 68 65 72   calls to either
333b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
333c0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  erface..**.** {F
333d0 31 36 37 30 36 7d 20 54 68 65 20 6e 61 6d 65 20  16706} The name 
333e0 6f 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64  of the requested
333f0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
33400 69 6f 6e 20 70 61 73 73 65 64 20 69 6e 20 74 68  ion passed in th
33410 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 34 74  e.**          4t
33420 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
33430 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
33440 6e 20 55 54 46 2d 38 20 69 66 20 74 68 65 20 63  n UTF-8 if the c
33450 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  allback.**      
33460 20 20 20 20 77 61 73 20 72 65 67 69 73 74 65 72      was register
33470 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
33480 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
33490 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20  ed()] and.**    
334a0 20 20 20 20 20 20 69 73 20 69 6e 20 55 54 46 2d        is in UTF-
334b0 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
334c0 72 64 65 72 20 69 66 20 74 68 65 20 63 61 6c 6c  rder if the call
334d0 62 61 63 6b 20 77 61 73 0a 2a 2a 20 20 20 20 20  back was.**     
334e0 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20       registered 
334f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
33500 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
33510 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 0a 2a 2f 0a  6()]..**.** .*/.
33520 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
33530 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20  ation_needed(.  
33540 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
33550 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  d*, .  void(*)(v
33560 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
33570 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
33580 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73   char*).);.int s
33590 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
335a0 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c  _needed16(.  sql
335b0 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
335c0 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
335d0 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
335e0 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69  extRep,const voi
335f0 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70  d*).);../*.** Sp
33600 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f  ecify the key fo
33610 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64  r an encrypted d
33620 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72  atabase.  This r
33630 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65  outine should be
33640 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74  .** called right
33650 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f   after sqlite3_o
33660 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  pen()..**.** The
33670 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
33680 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
33690 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
336a0 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
336b0 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
336c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
336d0 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
336e0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
336f0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
33700 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
33710 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
33720 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
33730 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
33740 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e  /.);../*.** Chan
33750 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e  ge the key on an
33760 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20   open database. 
33770 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   If the current 
33780 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a  database is not.
33790 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68  ** encrypted, th
337a0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
337b0 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20  encrypt it.  If 
337c0 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d  pNew==0 or nNew=
337d0 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  =0, the.** datab
337e0 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64  ase is decrypted
337f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
33800 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
33810 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
33820 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
33830 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
33840 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
33850 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
33860 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
33870 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33880 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
33890 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
338a0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
338b0 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
338c0 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
338d0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
338e0 49 33 52 45 46 3a 20 20 53 75 73 70 65 6e 64 20  I3REF:  Suspend 
338f0 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20  Execution For A 
33900 53 68 6f 72 74 20 54 69 6d 65 20 7b 46 31 30 35  Short Time {F105
33910 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  30}.**.** The sq
33920 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75  lite3_sleep() fu
33930 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 75 73 65 73  nction.** causes
33940 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72   the current thr
33950 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65  ead to suspend e
33960 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20  xecution.** for 
33970 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65  at least a numbe
33980 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
33990 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69  s specified in i
339a0 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ts parameter..**
339b0 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61  .** If the opera
339c0 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73  ting system does
339d0 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65   not support sle
339e0 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68  ep requests with
339f0 20 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64   .** millisecond
33a00 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e   time resolution
33a10 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20  , then the time 
33a20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20  will be rounded 
33a30 75 70 20 74 6f 20 0a 2a 2a 20 74 68 65 20 6e 65  up to .** the ne
33a40 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68  arest second. Th
33a50 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
33a60 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
33a70 70 20 61 63 74 75 61 6c 6c 79 20 0a 2a 2a 20 72  p actually .** r
33a80 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68  equested from th
33a90 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
33aa0 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  em is returned..
33ab0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70  **.** SQLite imp
33ac0 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74  lements this int
33ad0 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e  erface by callin
33ae0 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a  g the xSleep().*
33af0 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  * method of the 
33b00 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
33b10 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
33b20 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
33b30 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 33 7d 20 54  **.** {F10533} T
33b40 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65  he [sqlite3_slee
33b50 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20  p(M)] interface 
33b60 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 6c 65  invokes the xSle
33b70 65 70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  ep.**          m
33b80 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
33b90 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
33ba0 73 7c 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20  s|VFS] in order 
33bb0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  to.**          s
33bc0 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
33bd0 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   of the current 
33be0 74 68 72 65 61 64 20 66 6f 72 20 61 74 20 6c 65  thread for at le
33bf0 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ast.**          
33c00 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a  M milliseconds..
33c10 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 36 7d 20 54  **.** {F10536} T
33c20 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65  he [sqlite3_slee
33c30 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20  p(M)] interface 
33c40 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
33c50 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  er of.**        
33c60 20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f    milliseconds o
33c70 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
33c80 20 72 65 71 75 65 73 74 65 64 20 6f 66 20 74 68   requested of th
33c90 65 20 6f 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20  e operating.**  
33ca0 20 20 20 20 20 20 20 20 73 79 73 74 65 6d 2c 20          system, 
33cb0 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6c  which might be l
33cc0 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 70  arger than the p
33cd0 61 72 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69  arameter M..*/.i
33ce0 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  nt sqlite3_sleep
33cf0 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
33d00 50 49 33 52 45 46 3a 20 20 4e 61 6d 65 20 4f 66  PI3REF:  Name Of
33d10 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64   The Folder Hold
33d20 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69  ing Temporary Fi
33d30 6c 65 73 20 7b 46 31 30 33 31 30 7d 0a 2a 2a 0a  les {F10310}.**.
33d40 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f 62 61  ** If this globa
33d50 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61  l variable is ma
33d60 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61  de to point to a
33d70 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
33d80 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
33d90 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e  a folder (a.k.a.
33da0 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65   directory), the
33db0 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20  n all temporary 
33dc0 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  files.** created
33dd0 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   by SQLite will 
33de0 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61  be placed in tha
33df0 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20 49 66  t directory.  If
33e00 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
33e10 2a 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * is NULL pointe
33e20 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 64  r, then SQLite d
33e30 6f 65 73 20 61 20 73 65 61 72 63 68 20 66 6f 72  oes a search for
33e40 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
33e50 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 66 69 6c  temporary.** fil
33e60 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  e directory..**.
33e70 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
33e80 65 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 69 73  e to modify this
33e90 20 76 61 72 69 61 62 6c 65 20 6f 6e 63 65 20 61   variable once a
33ea0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
33eb0 74 69 6f 6e 0a 2a 2a 20 68 61 73 20 62 65 65 6e  tion.** has been
33ec0 20 6f 70 65 6e 65 64 2e 20 20 49 74 20 69 73 20   opened.  It is 
33ed0 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68  intended that th
33ee0 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73  is variable be s
33ef0 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61  et once.** as pa
33f00 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e  rt of process in
33f10 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
33f20 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69   before any SQLi
33f30 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  te interface.** 
33f40 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65  routines have be
33f50 65 6e 20 63 61 6c 6c 20 61 6e 64 20 72 65 6d 61  en call and rema
33f60 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 74 68 65  in unchanged the
33f70 72 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49  reafter..*/.SQLI
33f80 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a  TE_EXTERN char *
33f90 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
33fa0 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ectory;../*.** C
33fb0 41 50 49 33 52 45 46 3a 20 20 54 65 73 74 20 54  API3REF:  Test T
33fc0 6f 20 53 65 65 20 49 66 20 54 68 65 20 44 61 74  o See If The Dat
33fd0 61 62 61 73 65 20 49 73 20 49 6e 20 41 75 74 6f  abase Is In Auto
33fe0 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b 46 31  -Commit Mode {F1
33ff0 32 39 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  2930}.**.** The 
34000 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
34010 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61  commit() interfa
34020 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ce returns non-z
34030 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69  ero or.** zero i
34040 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61  f the given data
34050 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
34060 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20  is or is not in 
34070 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c  autocommit mode,
34080 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
34090 2e 20 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  .   Autocommit m
340a0 6f 64 65 20 69 73 20 6f 6e 0a 2a 2a 20 62 79 20  ode is on.** by 
340b0 64 65 66 61 75 6c 74 2e 20 20 41 75 74 6f 63 6f  default.  Autoco
340c0 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73  mmit mode is dis
340d0 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49  abled by a [BEGI
340e0 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  N] statement..**
340f0 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
34100 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62   is re-enabled b
34110 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20  y a [COMMIT] or 
34120 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a  [ROLLBACK]..**.*
34130 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e  * If certain kin
34140 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63  ds of errors occ
34150 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e  ur on a statemen
34160 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69  t within a multi
34170 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72  -statement.** tr
34180 61 6e 73 61 63 74 69 6f 6e 73 20 28 65 72 72 6f  ansactions (erro
34190 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51  rs including [SQ
341a0 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c  LITE_FULL], [SQL
341b0 49 54 45 5f 49 4f 45 52 52 5d 2c 20 0a 2a 2a 20  ITE_IOERR], .** 
341c0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20  [SQLITE_NOMEM], 
341d0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61  [SQLITE_BUSY], a
341e0 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  nd [SQLITE_INTER
341f0 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a  RUPT]) then the.
34200 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d  ** transaction m
34210 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62  ight be rolled b
34220 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
34230 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79  y.  The only way
34240 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20   to.** find out 
34250 69 66 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  if SQLite automa
34260 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
34270 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
34280 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20  ion after.** an 
34290 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20  error is to use 
342a0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  this function..*
342b0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
342c0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 31 7d 20  .**.** {F12931} 
342d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  The [sqlite3_get
342e0 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 44 29 5d 20  _autocommit(D)] 
342f0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
34300 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a  s non-zero or.**
34310 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 69            zero i
34320 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
34330 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 69 73  connection] D is
34340 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75   or is not in au
34350 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 20 20 20 20  tocommit.**     
34360 20 20 20 20 20 6d 6f 64 65 2c 20 72 65 73 70 65       mode, respe
34370 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b  ctively..**.** {
34380 46 31 32 39 33 32 7d 20 41 75 74 6f 63 6f 6d 6d  F12932} Autocomm
34390 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79  it mode is on by
343a0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
343b0 7b 46 31 32 39 33 33 7d 20 41 75 74 6f 63 6f 6d  {F12933} Autocom
343c0 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61  mit mode is disa
343d0 62 6c 65 64 20 62 79 20 61 20 73 75 63 63 65 73  bled by a succes
343e0 73 66 75 6c 20 5b 42 45 47 49 4e 5d 20 73 74 61  sful [BEGIN] sta
343f0 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46  tement..**.** {F
34400 31 32 39 33 34 7d 20 41 75 74 6f 63 6f 6d 6d 69  12934} Autocommi
34410 74 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65  t mode is enable
34420 64 20 62 79 20 61 20 73 75 63 63 65 73 73 66 75  d by a successfu
34430 6c 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52  l [COMMIT] or [R
34440 4f 4c 4c 42 41 43 4b 5d 0a 2a 2a 20 20 20 20 20  OLLBACK].**     
34450 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 2e 0a       statement..
34460 2a 2a 20 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49 54 41  ** .**.** LIMITA
34470 54 49 4f 4e 53 3a 0a 2a 2a 2a 0a 2a 2a 20 7b 55  TIONS:.***.** {U
34480 31 32 39 33 36 7d 20 49 66 20 61 6e 6f 74 68 65  12936} If anothe
34490 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73  r thread changes
344a0 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20   the autocommit 
344b0 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61  status of the da
344c0 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20 20 20  tabase.**       
344d0 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68     connection wh
344e0 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ile this routine
344f0 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65   is running, the
34500 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
34510 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ue.**          i
34520 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  s undefined..*/.
34530 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
34540 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74  autocommit(sqlit
34550 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
34560 49 33 52 45 46 3a 20 20 46 69 6e 64 20 54 68 65  I3REF:  Find The
34570 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65   Database Handle
34580 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53   Of A Prepared S
34590 74 61 74 65 6d 65 6e 74 20 7b 46 31 33 31 32 30  tatement {F13120
345a0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
345b0 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e  te3_db_handle in
345c0 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72  terface.** retur
345d0 6e 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 2a  ns the [sqlite3*
345e0 5d 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  ] database handl
345f0 65 20 74 6f 20 77 68 69 63 68 20 61 0a 2a 2a 20  e to which a.** 
34600 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
34610 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 0a 2a 2a  ent] belongs..**
34620 20 54 68 65 20 64 61 74 61 62 61 73 65 20 68 61   The database ha
34630 6e 64 6c 65 20 72 65 74 75 72 6e 65 64 20 62 79  ndle returned by
34640 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
34650 6c 65 0a 2a 2a 20 69 73 20 74 68 65 20 73 61 6d  le.** is the sam
34660 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  e database handl
34670 65 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 74 68  e that was.** th
34680 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
34690 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
346a0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
346b0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a 2a  r its variants.*
346c0 2a 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20  * that was used 
346d0 74 6f 20 63 72 65 61 74 65 20 74 68 65 20 73 74  to create the st
346e0 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66  atement in the f
346f0 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a  irst place..**.*
34700 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
34710 0a 2a 2a 20 7b 46 31 33 31 32 33 7d 20 54 68 65  .** {F13123} The
34720 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e   [sqlite3_db_han
34730 64 6c 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63  dle(S)] interfac
34740 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
34750 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
34760 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
34770 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73   connection] ass
34780 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20  ociated with.** 
34790 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
347a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
347b0 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
347c0 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73  ite3_db_handle(s
347d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
347e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
347f0 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70   Find the next p
34800 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34810 74 20 7b 46 31 33 31 34 30 7d 0a 2a 2a 0a 2a 2a  t {F13140}.**.**
34820 20 52 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65   Return a pointe
34830 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70  r to the next [p
34840 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34850 74 5d 20 61 66 74 65 72 20 70 53 74 6d 74 0a 2a  t] after pStmt.*
34860 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
34870 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  h [database conn
34880 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 49 66  ection] pDb.  If
34890 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a   pStmt is NULL.*
348a0 2a 20 74 68 65 6e 20 72 65 74 75 72 6e 20 61 20  * then return a 
348b0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
348c0 69 72 73 74 20 5b 70 72 65 70 61 72 65 64 20 73  irst [prepared s
348d0 74 61 74 65 6d 65 6e 74 5d 20 61 73 73 6f 63 69  tatement] associ
348e0 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ated.** with the
348f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
34900 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 49 66 20  ction] pDb.  If 
34910 6e 6f 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  no [prepared sta
34920 74 65 6d 65 6e 74 5d 0a 2a 2a 20 73 61 74 69 73  tement].** satis
34930 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69  fies the conditi
34940 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ons of this rout
34950 69 6e 65 2c 20 72 65 74 75 72 6e 20 4e 55 4c 4c  ine, return NULL
34960 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
34970 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31 34  TS:.**.** {F1314
34980 33 7d 20 49 66 20 44 20 69 73 20 61 20 5b 64 61  3} If D is a [da
34990 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
349a0 6e 5d 20 74 68 61 74 20 68 6f 6c 64 73 20 6f 6e  n] that holds on
349b0 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20  e or more.**    
349c0 20 20 20 20 20 20 75 6e 66 69 6e 61 6c 69 7a 65        unfinalize
349d0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
349e0 65 6d 65 6e 74 73 5d 20 61 6e 64 20 53 20 69 73  ements] and S is
349f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
34a00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
34a10 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  n [sqlite3_next_
34a20 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75 74  stmt(D, S)] rout
34a30 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e  ine shall return
34a40 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20   a pointer.**   
34a50 20 20 20 20 20 20 20 74 6f 20 6f 6e 65 20 6f 66         to one of
34a60 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
34a70 74 61 74 65 6d 65 6e 74 73 5d 20 61 73 73 6f 63  tatements] assoc
34a80 69 61 74 65 64 20 77 69 74 68 20 44 2e 0a 2a 2a  iated with D..**
34a90 0a 2a 2a 20 7b 46 31 33 31 34 36 7d 20 49 66 20  .** {F13146} If 
34aa0 44 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  D is a [database
34ab0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
34ac0 74 20 68 6f 6c 64 73 20 6e 6f 0a 2a 2a 20 20 20  t holds no.**   
34ad0 20 20 20 20 20 20 20 75 6e 66 69 6e 61 6c 69 7a         unfinaliz
34ae0 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed [prepared sta
34af0 74 65 6d 65 6e 74 73 5d 20 61 6e 64 20 53 20 69  tements] and S i
34b00 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
34b10 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
34b20 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74  en [sqlite3_next
34b30 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75  _stmt(D, S)] rou
34b40 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72  tine shall retur
34b50 6e 20 61 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20  n a NULL.**     
34b60 20 20 20 20 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a       pointer..**
34b70 0a 2a 2a 20 7b 46 31 33 31 34 39 7d 20 49 66 20  .** {F13149} If 
34b80 53 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  S is a [prepared
34b90 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 5b   statement] in [
34ba0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34bb0 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20  ion] D.**       
34bc0 20 20 20 61 6e 64 20 53 20 69 73 20 6e 6f 74 20     and S is not 
34bd0 74 68 65 20 6c 61 73 74 20 5b 70 72 65 70 61 72  the last [prepar
34be0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
34bf0 20 44 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20   D, then.**     
34c00 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65       [sqlite3_ne
34c10 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72  xt_stmt(D, S)] r
34c20 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74  outine shall ret
34c30 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  urn a pointer.**
34c40 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65            to the
34c50 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20   next [prepared 
34c60 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 44 20  statement] in D 
34c70 61 66 74 65 72 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b  after S..**.** {
34c80 46 31 33 31 35 32 7d 20 49 66 20 53 20 69 73 20  F13152} If S is 
34c90 74 68 65 20 6c 61 73 74 20 5b 70 72 65 70 61 72  the last [prepar
34ca0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
34cb0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
34cc0 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20  ction] D.**     
34cd0 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74       then [sqlit
34ce0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20  e3_next_stmt(D, 
34cf0 53 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c  S)] routine shal
34d00 6c 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 0a  l return a NULL.
34d10 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e  **          poin
34d20 74 65 72 2e 0a 2a 2a 0a 2a 2f 0a 73 71 6c 69 74  ter..**.*/.sqlit
34d30 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33  e3_stmt *sqlite3
34d40 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74  _next_stmt(sqlit
34d50 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33  e3 *pDb, sqlite3
34d60 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
34d70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34d80 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c   Commit And Roll
34d90 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f  back Notificatio
34da0 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46 31 32  n Callbacks {F12
34db0 39 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  950}.**.** The s
34dc0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
34dd0 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
34de0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
34df0 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
34e00 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
34e10 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63  enever a transac
34e20 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65  tion is committe
34e30 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61  d..** Any callba
34e40 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76  ck set by a prev
34e50 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ious call to sql
34e60 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
34e70 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  ().** for the sa
34e80 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
34e90 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
34ea0 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  dden..** The sql
34eb0 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
34ec0 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
34ed0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
34ee0 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
34ef0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
34f00 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63  enever a transac
34f10 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65  tion is committe
34f20 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61  d..** Any callba
34f30 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76  ck set by a prev
34f40 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ious call to sql
34f50 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
34f60 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  ().** for the sa
34f70 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
34f80 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
34f90 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70 41 72  dden..** The pAr
34fa0 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61  g argument is pa
34fb0 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20  ssed through.** 
34fc0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  to the callback.
34fd0 20 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63    If the callbac
34fe0 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f  k on a commit ho
34ff0 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 0a 2a 2a 20  ok function .** 
35000 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
35010 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69  , then the commi
35020 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69  t is converted i
35030 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a  nto a rollback..
35040 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
35050 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72   function was pr
35060 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
35070 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67  red, its.** pArg
35080 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
35090 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e  ed.  Otherwise N
350a0 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
350b0 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 69  .**.** Registeri
350c0 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69  ng a NULL functi
350d0 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  on disables the 
350e0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
350f0 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
35100 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20   of this API, a 
35110 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73  transaction is s
35120 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e  aid to have been
35130 20 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b   .** rolled back
35140 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   if an explicit 
35150 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65  "ROLLBACK" state
35160 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64  ment is executed
35170 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  , or.** an error
35180 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63   or constraint c
35190 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69  auses an implici
351a0 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63  t rollback to oc
351b0 63 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c  cur..** The roll
351c0 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  back callback is
351d0 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20   not invoked if 
351e0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
351f0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
35200 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65  y rolled back be
35210 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61  cause the databa
35220 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
35230 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68 65 20   closed..** The 
35240 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63  rollback callbac
35250 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
35260 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f   if a transactio
35270 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62  n is.** rolled b
35280 61 63 6b 20 62 65 63 61 75 73 65 20 61 20 63 6f  ack because a co
35290 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65  mmit callback re
352a0 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e  turned non-zero.
352b0 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65 63 6b  .** <todo> Check
352c0 20 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64 6f 3e   on this </todo>
352d0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
352e0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e   experimental in
352f0 74 65 72 66 61 63 65 73 20 61 6e 64 20 61 72 65  terfaces and are
35300 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
35310 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ge..**.** INVARI
35320 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ANTS:.**.** {F12
35330 39 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  951} The [sqlite
35340 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c  3_commit_hook(D,
35350 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  F,P)] interface 
35360 72 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a 2a  registers the.**
35370 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
35380 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f  ck function F to
35390 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
353a0 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e   argument P when
353b0 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ever.**         
353c0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63   a transaction c
353d0 6f 6d 6d 69 74 73 20 6f 6e 20 5b 64 61 74 61 62  ommits on [datab
353e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
353f0 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 32  D..**.** {F12952
35400 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
35410 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50  ommit_hook(D,F,P
35420 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
35430 75 72 6e 73 20 74 68 65 20 50 0a 2a 2a 20 20 20  urns the P.**   
35440 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20         argument 
35450 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75  from the previou
35460 73 20 63 61 6c 6c 20 77 69 74 68 20 74 68 65 20  s call with the 
35470 73 61 6d 65 20 0a 2a 2a 20 20 20 20 20 20 20 20  same .**        
35480 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e    [database conn
35490 65 63 74 69 6f 6e 20 5d 20 44 20 2c 20 6f 72 20  ection ] D , or 
354a0 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72 73  NULL on the firs
354b0 74 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20  t call.**       
354c0 20 20 20 66 6f 72 20 61 20 70 61 72 74 69 63 75     for a particu
354d0 6c 61 72 20 5b 64 61 74 61 62 61 73 65 20 63 6f  lar [database co
354e0 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
354f0 2a 2a 20 7b 46 31 32 39 35 33 7d 20 45 61 63 68  ** {F12953} Each
35500 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
35510 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d  3_commit_hook()]
35520 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65 20   overwrites the 
35530 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
35540 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20       registered 
35550 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a  by prior calls..
35560 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 34 7d 20 49  **.** {F12954} I
35570 66 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e 74  f the F argument
35580 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
35590 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d  mit_hook(D,F,P)]
355a0 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20   is NULL.**     
355b0 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 63 6f       then the co
355c0 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61  mmit hook callba
355d0 63 6b 20 69 73 20 63 61 6e 63 65 6c 65 64 20 61  ck is canceled a
355e0 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a  nd no callback.*
355f0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e  *          is in
35600 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 74 72 61  voked when a tra
35610 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73  nsaction commits
35620 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 35 7d  ..**.** {F12955}
35630 20 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 63   If the commit c
35640 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
35650 6e 6f 6e 2d 7a 65 72 6f 20 74 68 65 6e 20 74 68  non-zero then th
35660 65 20 63 6f 6d 6d 69 74 20 69 73 0a 2a 2a 20 20  e commit is.**  
35670 20 20 20 20 20 20 20 20 63 6f 6e 76 65 72 74 65          converte
35680 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63  d into a rollbac
35690 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 31  k..**.** {F12961
356a0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
356b0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46  ollback_hook(D,F
356c0 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,P)] interface r
356d0 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a 2a 20  egisters the.** 
356e0 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
356f0 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20  k function F to 
35700 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
35710 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65  argument P whene
35720 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ver.**          
35730 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f  a transaction ro
35740 6c 6c 73 20 62 61 63 6b 20 6f 6e 20 5b 64 61 74  lls back on [dat
35750 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35760 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ] D..**.** {F129
35770 36 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  62} The [sqlite3
35780 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
35790 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
357a0 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 0a 2a   returns the P.*
357b0 2a 20 20 20 20 20 20 20 20 20 20 61 72 67 75 6d  *          argum
357c0 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
357d0 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 20  vious call with 
357e0 74 68 65 20 73 61 6d 65 20 0a 2a 2a 20 20 20 20  the same .**    
357f0 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
35800 63 6f 6e 6e 65 63 74 69 6f 6e 20 5d 20 44 20 2c  connection ] D ,
35810 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20   or NULL on the 
35820 66 69 72 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20  first call.**   
35830 20 20 20 20 20 20 20 66 6f 72 20 61 20 70 61 72         for a par
35840 74 69 63 75 6c 61 72 20 5b 64 61 74 61 62 61 73  ticular [databas
35850 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e  e connection] D.
35860 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 33 7d 20  .**.** {F12963} 
35870 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71  Each call to [sq
35880 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
35890 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69 74 65  ook()] overwrite
358a0 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
358b0 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73  *          regis
358c0 74 65 72 65 64 20 62 79 20 70 72 69 6f 72 20 63  tered by prior c
358d0 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  alls..**.** {F12
358e0 39 36 34 7d 20 49 66 20 74 68 65 20 46 20 61 72  964} If the F ar
358f0 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
35900 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
35910 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c  (D,F,P)] is NULL
35920 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
35930 6e 20 74 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68  n the rollback h
35940 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ook callback is 
35950 63 61 6e 63 65 6c 65 64 20 61 6e 64 20 6e 6f 20  canceled and no 
35960 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
35970 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20       is invoked 
35980 77 68 65 6e 20 61 20 74 72 61 6e 73 61 63 74 69  when a transacti
35990 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 2e 0a 2a  on rolls back..*
359a0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
359b0 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69  commit_hook(sqli
359c0 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
359d0 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69  d*), void*);.voi
359e0 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  d *sqlite3_rollb
359f0 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  ack_hook(sqlite3
35a00 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20  *, void(*)(void 
35a10 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
35a20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
35a30 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63  a Change Notific
35a40 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20  ation Callbacks 
35a50 7b 46 31 32 39 37 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12970}.**.** T
35a60 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74  he sqlite3_updat
35a70 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  e_hook() interfa
35a80 63 65 0a 2a 2a 20 72 65 67 69 73 74 65 72 73 20  ce.** registers 
35a90 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
35aa0 69 6f 6e 20 77 69 74 68 20 74 68 65 20 64 61 74  ion with the dat
35ab0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35ac0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
35ad0 68 65 20 0a 2a 2a 20 66 69 72 73 74 20 61 72 67  he .** first arg
35ae0 75 6d 65 6e 74 20 74 6f 20 62 65 20 69 6e 76 6f  ument to be invo
35af0 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72  ked whenever a r
35b00 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69  ow is updated, i
35b10 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
35b20 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62  ed..** Any callb
35b30 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
35b40 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
35b50 69 73 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20  is function for 
35b60 74 68 65 20 73 61 6d 65 20 0a 2a 2a 20 64 61 74  the same .** dat
35b70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35b80 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
35b90 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
35ba0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
35bb0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75  ointer to the fu
35bc0 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65  nction to invoke
35bd0 20 77 68 65 6e 20 61 20 0a 2a 2a 20 72 6f 77 20   when a .** row 
35be0 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
35bf0 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
35c00 20 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61   .** The first a
35c10 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
35c20 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 61 20  allback is.** a 
35c30 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
35c40 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
35c50 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
35c60 6b 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  k()..** The seco
35c70 6e 64 20 63 61 6c 6c 62 61 63 6b 20 0a 2a 2a 20  nd callback .** 
35c80 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
35c90 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52  of [SQLITE_INSER
35ca0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45  T], [SQLITE_DELE
35cb0 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  TE] or [SQLITE_U
35cc0 50 44 41 54 45 5d 2c 0a 2a 2a 20 64 65 70 65 6e  PDATE],.** depen
35cd0 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72  ding on the oper
35ce0 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65  ation that cause
35cf0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 74  d the callback t
35d00 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  o be invoked..**
35d10 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 0a   The third and .
35d20 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  ** fourth argume
35d30 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  nts to the callb
35d40 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e  ack contain poin
35d50 74 65 72 73 20 74 6f 20 74 68 65 20 64 61 74 61  ters to the data
35d60 62 61 73 65 20 61 6e 64 20 0a 2a 2a 20 74 61 62  base and .** tab
35d70 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69  le name containi
35d80 6e 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20  ng the affected 
35d90 72 6f 77 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61  row..** The fina
35da0 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d  l callback param
35db0 65 74 65 72 20 69 73 20 0a 2a 2a 20 74 68 65 20  eter is .** the 
35dc0 72 6f 77 69 64 20 6f 66 20 74 68 65 20 72 6f 77  rowid of the row
35dd0 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 63 61 73 65  ..** In the case
35de0 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74   of an update, t
35df0 68 69 73 20 69 73 20 74 68 65 20 72 6f 77 69 64  his is the rowid
35e00 20 61 66 74 65 72 20 0a 2a 2a 20 74 68 65 20 75   after .** the u
35e10 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63  pdate takes plac
35e20 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64  e..**.** The upd
35e30 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20  ate hook is not 
35e40 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74  invoked when int
35e50 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62  ernal system tab
35e60 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66  les are.** modif
35e70 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65  ied (i.e. sqlite
35e80 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69  _master and sqli
35e90 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a 2a  te_sequence)..**
35ea0 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66  .** If another f
35eb0 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76  unction was prev
35ec0 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65  iously registere
35ed0 64 2c 20 69 74 73 20 70 41 72 67 20 76 61 6c 75  d, its pArg valu
35ee0 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  e.** is returned
35ef0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c  .  Otherwise NUL
35f00 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  L is returned..*
35f10 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
35f20 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 31 7d 20  .**.** {F12971} 
35f30 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64  The [sqlite3_upd
35f40 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d  ate_hook(D,F,P)]
35f50 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
35f60 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  s callback.**   
35f70 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20         function 
35f80 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  F to be invoked 
35f90 77 69 74 68 20 66 69 72 73 74 20 70 61 72 61 6d  with first param
35fa0 65 74 65 72 20 50 20 77 68 65 6e 65 76 65 72 0a  eter P whenever.
35fb0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 61  **          a ta
35fc0 62 6c 65 20 72 6f 77 20 69 73 20 6d 6f 64 69 66  ble row is modif
35fd0 69 65 64 2c 20 69 6e 73 65 72 74 65 64 2c 20 6f  ied, inserted, o
35fe0 72 20 64 65 6c 65 74 65 64 20 6f 6e 0a 2a 2a 20  r deleted on.** 
35ff0 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
36000 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
36010 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 33 7d  ..**.** {F12973}
36020 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70   The [sqlite3_up
36030 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  date_hook(D,F,P)
36040 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
36050 72 6e 73 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  rns the value.**
36060 20 20 20 20 20 20 20 20 20 20 6f 66 20 50 20 66            of P f
36070 6f 72 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  or the previous 
36080 63 61 6c 6c 20 6f 6e 20 74 68 65 20 73 61 6d 65  call on the same
36090 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
360a0 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20 20  ction] D,.**    
360b0 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 66 6f        or NULL fo
360c0 72 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  r the first call
360d0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 35 7d  ..**.** {F12975}
360e0 20 49 66 20 74 68 65 20 75 70 64 61 74 65 20 68   If the update h
360f0 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 46 20 69  ook callback F i
36100 6e 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  n [sqlite3_updat
36110 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 0a 2a  e_hook(D,F,P)].*
36120 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 4e 55  *          is NU
36130 4c 4c 20 74 68 65 6e 20 74 68 65 20 6e 6f 20 75  LL then the no u
36140 70 64 61 74 65 20 63 61 6c 6c 62 61 63 6b 73 20  pdate callbacks 
36150 61 72 65 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20  are made..**.** 
36160 7b 46 31 32 39 37 37 7d 20 45 61 63 68 20 63 61  {F12977} Each ca
36170 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 75  ll to [sqlite3_u
36180 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50  pdate_hook(D,F,P
36190 29 5d 20 6f 76 65 72 72 69 64 65 73 20 70 72 69  )] overrides pri
361a0 6f 72 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20  or calls.**     
361b0 20 20 20 20 20 74 6f 20 74 68 65 20 73 61 6d 65       to the same
361c0 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 20 74 68   interface on th
361d0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
361e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a   connection] D..
361f0 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 39 7d 20 54  **.** {F12979} T
36200 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 63  he update hook c
36210 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69  allback is not i
36220 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65  nvoked when inte
36230 72 6e 61 6c 20 73 79 73 74 65 6d 0a 2a 2a 20 20  rnal system.**  
36240 20 20 20 20 20 20 20 20 74 61 62 6c 65 73 20 73          tables s
36250 75 63 68 20 61 73 20 73 71 6c 69 74 65 5f 6d 61  uch as sqlite_ma
36260 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f  ster and sqlite_
36270 73 65 71 75 65 6e 63 65 20 61 72 65 20 6d 6f 64  sequence are mod
36280 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ified..**.** {F1
36290 32 39 38 31 7d 20 54 68 65 20 73 65 63 6f 6e 64  2981} The second
362a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
362b0 65 20 75 70 64 61 74 65 20 63 61 6c 6c 62 61 63  e update callbac
362c0 6b 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  k .**          i
362d0 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
362e0 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54  _INSERT], [SQLIT
362f0 45 5f 44 45 4c 45 54 45 5d 20 6f 72 20 5b 53 51  E_DELETE] or [SQ
36300 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a  LITE_UPDATE],.**
36310 20 20 20 20 20 20 20 20 20 20 64 65 70 65 6e 64            depend
36320 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61  ing on the opera
36330 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64  tion that caused
36340 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f   the callback to
36350 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   be invoked..**.
36360 2a 2a 20 7b 46 31 32 39 38 33 7d 20 54 68 65 20  ** {F12983} The 
36370 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68  third and fourth
36380 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
36390 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
363a0 69 6e 20 70 6f 69 6e 74 65 72 73 0a 2a 2a 20 20  in pointers.**  
363b0 20 20 20 20 20 20 20 20 74 6f 20 7a 65 72 6f 2d          to zero-
363c0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
363d0 20 73 74 72 69 6e 67 73 20 77 68 69 63 68 20 61   strings which a
363e0 72 65 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  re the names of 
363f0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
36400 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62  database and tab
36410 6c 65 20 74 68 61 74 20 69 73 20 62 65 69 6e 67  le that is being
36420 20 75 70 64 61 74 65 64 2e 0a 0a 2a 2a 20 7b 46   updated...** {F
36430 31 32 39 38 35 7d 20 54 68 65 20 66 69 6e 61 6c  12985} The final
36440 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65   callback parame
36450 74 65 72 20 69 73 20 74 68 65 20 72 6f 77 69 64  ter is the rowid
36460 20 6f 66 20 74 68 65 20 72 6f 77 20 61 66 74 65   of the row afte
36470 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
36480 65 20 63 68 61 6e 67 65 20 6f 63 63 75 72 73 2e  e change occurs.
36490 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
364a0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20  3_update_hook(. 
364b0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
364c0 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74  id(*)(void *,int
364d0 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63   ,char const *,c
364e0 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69  har const *,sqli
364f0 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f  te3_int64),.  vo
36500 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  id*.);../*.** CA
36510 50 49 33 52 45 46 3a 20 20 45 6e 61 62 6c 65 20  PI3REF:  Enable 
36520 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65  Or Disable Share
36530 64 20 50 61 67 65 72 20 43 61 63 68 65 20 7b 46  d Pager Cache {F
36540 31 30 33 33 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52  10330}.** KEYWOR
36550 44 53 3a 20 7b 73 68 61 72 65 64 20 63 61 63 68  DS: {shared cach
36560 65 7d 20 7b 73 68 61 72 65 64 20 63 61 63 68 65  e} {shared cache
36570 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69   mode}.**.** Thi
36580 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  s routine enable
36590 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
365a0 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65  e sharing of the
365b0 20 64 61 74 61 62 61 73 65 20 63 61 63 68 65 0a   database cache.
365c0 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61  ** and schema da
365d0 74 61 20 73 74 72 75 63 74 75 72 65 73 20 62 65  ta structures be
365e0 74 77 65 65 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e  tween connection
365f0 73 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61  s to the same da
36600 74 61 62 61 73 65 2e 0a 2a 2a 20 53 68 61 72 69  tabase..** Shari
36610 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66  ng is enabled if
36620 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   the argument is
36630 20 74 72 75 65 20 61 6e 64 20 64 69 73 61 62 6c   true and disabl
36640 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  ed if the argume
36650 6e 74 0a 2a 2a 20 69 73 20 66 61 6c 73 65 2e 0a  nt.** is false..
36660 2a 2a 0a 2a 2a 20 43 61 63 68 65 20 73 68 61 72  **.** Cache shar
36670 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61  ing is enabled a
36680 6e 64 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 66  nd disabled.** f
36690 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f  or an entire pro
366a0 63 65 73 73 2e 20 7b 45 4e 44 7d 20 54 68 69 73  cess. {END} This
366b0 20 69 73 20 61 20 63 68 61 6e 67 65 20 61 73 20   is a change as 
366c0 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
366d0 6e 20 33 2e 35 2e 30 2e 0a 2a 2a 20 49 6e 20 70  n 3.5.0..** In p
366e0 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  rior versions of
366f0 20 53 51 4c 69 74 65 2c 20 73 68 61 72 69 6e 67   SQLite, sharing
36700 20 77 61 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20   was.** enabled 
36710 6f 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20  or disabled for 
36720 65 61 63 68 20 74 68 72 65 61 64 20 73 65 70 61  each thread sepa
36730 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  rately..**.** Th
36740 65 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 20  e cache sharing 
36750 6d 6f 64 65 20 73 65 74 20 62 79 20 74 68 69 73  mode set by this
36760 20 69 6e 74 65 72 66 61 63 65 20 65 66 66 65 63   interface effec
36770 74 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  ts all subsequen
36780 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73  t.** calls to [s
36790 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
367a0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
367b0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
367c0 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20  3_open16()]..** 
367d0 45 78 69 73 74 69 6e 67 20 64 61 74 61 62 61 73  Existing databas
367e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f  e connections co
367f0 6e 74 69 6e 75 65 20 75 73 65 20 74 68 65 20 73  ntinue use the s
36800 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74  haring mode.** t
36810 68 61 74 20 77 61 73 20 69 6e 20 65 66 66 65 63  hat was in effec
36820 74 20 61 74 20 74 68 65 20 74 69 6d 65 20 74 68  t at the time th
36830 65 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 0a  ey were opened..
36840 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61  **.** Virtual ta
36850 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62 65 20 75  bles cannot be u
36860 73 65 64 20 77 69 74 68 20 61 20 73 68 61 72 65  sed with a share
36870 64 20 63 61 63 68 65 2e 20 20 20 57 68 65 6e 20  d cache.   When 
36880 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
36890 69 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20  is enabled, the 
368a0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
368b0 6d 6f 64 75 6c 65 28 29 5d 20 41 50 49 20 75 73  module()] API us
368c0 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a  ed to register.*
368d0 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73  * virtual tables
368e0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
368f0 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a  urn an error..**
36900 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
36910 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
36920 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63  _OK] if shared c
36930 61 63 68 65 20 77 61 73 0a 2a 2a 20 65 6e 61 62  ache was.** enab
36940 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20  led or disabled 
36950 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41  successfully.  A
36960 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a  n [error code].*
36970 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74  * is returned ot
36980 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53  herwise..**.** S
36990 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64  hared cache is d
369a0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
369b0 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67  lt. But this mig
369c0 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ht change in.** 
369d0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
369e0 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c  of SQLite.  Appl
369f0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61  ications that ca
36a00 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a  re about shared.
36a10 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67  ** cache setting
36a20 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65   should set it e
36a30 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a  xplicitly..**.**
36a40 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 20   INVARIANTS:.** 
36a50 0a 2a 2a 20 7b 46 31 30 33 33 31 7d 20 41 20 73  .** {F10331} A s
36a60 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
36a70 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
36a80 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
36a90 61 63 68 65 28 42 29 5d 0a 2a 2a 20 20 20 20 20  ache(B)].**     
36aa0 20 20 20 20 20 77 69 6c 6c 20 65 6e 61 62 6c 65       will enable
36ab0 20 6f 72 20 64 69 73 61 62 6c 65 20 73 68 61 72   or disable shar
36ac0 65 64 20 63 61 63 68 65 20 6d 6f 64 65 20 66 6f  ed cache mode fo
36ad0 72 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  r any subsequent
36ae0 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  ly.**          c
36af0 72 65 61 74 65 64 20 5b 64 61 74 61 62 61 73 65  reated [database
36b00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 20   connection] in 
36b10 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73  the same process
36b20 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 36 7d  ..**.** {F10336}
36b30 20 57 68 65 6e 20 73 68 61 72 65 64 20 63 61 63   When shared cac
36b40 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 74  he is enabled, t
36b50 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
36b60 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 0a 2a 2a 20  te_module()].** 
36b70 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
36b80 63 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72  ce will always r
36b90 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a  eturn an error..
36ba0 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33 37 7d 20 54  **.** {F10337} T
36bb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  he [sqlite3_enab
36bc0 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
36bd0 42 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  B)] interface re
36be0 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
36bf0 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66    [SQLITE_OK] if
36c00 20 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61   shared cache wa
36c10 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  s enabled or dis
36c20 61 62 6c 65 64 20 73 75 63 63 65 73 73 66 75 6c  abled successful
36c30 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 33 33  ly..**.** {F1033
36c40 39 7d 20 53 68 61 72 65 64 20 63 61 63 68 65 20  9} Shared cache 
36c50 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
36c60 65 66 61 75 6c 74 2e 0a 2a 2f 0a 69 6e 74 20 73  efault..*/.int s
36c70 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
36c80 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b  ared_cache(int);
36c90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36ca0 3a 20 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72  :  Attempt To Fr
36cb0 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 20 7b  ee Heap Memory {
36cc0 46 31 37 33 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F17340}.**.** Th
36cd0 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  e sqlite3_releas
36ce0 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72  e_memory() inter
36cf0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
36d00 0a 2a 2a 20 66 72 65 65 20 4e 20 62 79 74 65 73  .** free N bytes
36d10 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
36d20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20  by deallocating 
36d30 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65  non-essential me
36d40 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
36d50 6f 6e 73 20 68 65 6c 64 20 62 79 20 74 68 65 20  ons held by the 
36d60 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79  database library
36d70 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20  . {END}  Memory 
36d80 75 73 65 64 0a 2a 2a 20 74 6f 20 63 61 63 68 65  used.** to cache
36d90 20 64 61 74 61 62 61 73 65 20 70 61 67 65 73 20   database pages 
36da0 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  to improve perfo
36db0 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61  rmance is an exa
36dc0 6d 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6f 6e 2d 65  mple of.** non-e
36dd0 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e  ssential memory.
36de0 20 20 53 71 6c 69 74 65 33 5f 72 65 6c 65 61 73    Sqlite3_releas
36df0 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72  e_memory() retur
36e00 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
36e10 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c   of bytes actual
36e20 6c 79 20 66 72 65 65 64 2c 20 77 68 69 63 68 20  ly freed, which 
36e30 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72  might be more or
36e40 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 74 68   less.** than th
36e50 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74  e amount request
36e60 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
36e70 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  ANTS:.**.** {F17
36e80 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  341} The [sqlite
36e90 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
36ea0 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  (N)] interface a
36eb0 74 74 65 6d 70 74 73 20 74 6f 0a 2a 2a 20 20 20  ttempts to.**   
36ec0 20 20 20 20 20 20 20 66 72 65 65 20 4e 20 62 79         free N by
36ed0 74 65 73 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  tes of heap memo
36ee0 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69  ry by deallocati
36ef0 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c  ng non-essential
36f00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d  .**          mem
36f10 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
36f20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61  held by the data
36f30 62 61 73 65 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  base library..**
36f40 0a 2a 2a 20 7b 46 31 36 33 34 32 7d 20 54 68 65  .** {F16342} The
36f50 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
36f60 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20 72 65 74  e_memory(N)] ret
36f70 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 0a  urns the number.
36f80 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 62  **          of b
36f90 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72  ytes actually fr
36fa0 65 65 64 2c 20 77 68 69 63 68 20 6d 69 67 68 74  eed, which might
36fb0 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73   be more or less
36fc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61  .**          tha
36fd0 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71  n the amount req
36fe0 75 65 73 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  uested..*/.int s
36ff0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
37000 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  emory(int);../*.
37010 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 20 49 6d  ** CAPI3REF:  Im
37020 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20  pose A Limit On 
37030 48 65 61 70 20 53 69 7a 65 20 7b 46 31 37 33 35  Heap Size {F1735
37040 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0}.**.** The sql
37050 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
37060 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65  imit() interface
37070 0a 2a 2a 20 70 6c 61 63 65 73 20 61 20 22 73 6f  .** places a "so
37080 66 74 22 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65  ft" limit on the
37090 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20   amount of heap 
370a0 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20  memory that may 
370b0 62 65 20 61 6c 6c 6f 63 61 74 65 64 0a 2a 2a 20  be allocated.** 
370c0 62 79 20 53 51 4c 69 74 65 2e 20 49 66 20 61 6e  by SQLite. If an
370d0 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61   internal alloca
370e0 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
370f0 64 20 0a 2a 2a 20 74 68 61 74 20 77 6f 75 6c 64  d .** that would
37100 20 65 78 63 65 65 64 20 74 68 65 20 73 6f 66 74   exceed the soft
37110 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71   heap limit, [sq
37120 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
37130 6d 6f 72 79 28 29 5d 20 69 73 0a 2a 2a 20 69 6e  mory()] is.** in
37140 76 6f 6b 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  voked one or mor
37150 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20  e times to free 
37160 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62 65  up some space be
37170 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 74  fore the allocat
37180 69 6f 6e 0a 2a 2a 20 69 73 20 6d 61 64 65 2e 0a  ion.** is made..
37190 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d 69 74 20  **.** The limit 
371a0 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 22  is called "soft"
371b0 2c 20 62 65 63 61 75 73 65 20 69 66 0a 2a 2a 20  , because if.** 
371c0 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
371d0 5f 6d 65 6d 6f 72 79 28 29 5d 20 63 61 6e 6e 6f  _memory()] canno
371e0 74 0a 2a 2a 20 66 72 65 65 20 73 75 66 66 69 63  t.** free suffic
371f0 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70  ient memory to p
37200 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74  revent the limit
37210 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65   from being exce
37220 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d  eded,.** the mem
37230 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64  ory is allocated
37240 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20   anyway and the 
37250 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f  current operatio
37260 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a  n proceeds..**.*
37270 2a 20 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20  * A negative or 
37280 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e  zero value for N
37290 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72   means that ther
372a0 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61  e is no soft hea
372b0 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b  p limit and.** [
372c0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
372d0 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f  memory()] will o
372e0 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
372f0 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68  en memory is exh
37300 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68 65 20 64  austed..** The d
37310 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72  efault value for
37320 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
37330 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  imit is zero..**
37340 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
37350 20 61 20 62 65 73 74 20 65 66 66 6f 72 74 20 74   a best effort t
37360 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74  o honor the soft
37370 20 68 65 61 70 20 6c 69 6d 69 74 2e 20 20 0a 2a   heap limit.  .*
37380 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 6f 66  * But if the sof
37390 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e  t heap limit can
373a0 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20  not be honored, 
373b0 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a  execution will.*
373c0 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f  * continue witho
373d0 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69  ut error or noti
373e0 66 69 63 61 74 69 6f 6e 2e 20 20 54 68 69 73 20  fication.  This 
373f0 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74  is why the limit
37400 20 69 73 20 0a 2a 2a 20 63 61 6c 6c 65 64 20 61   is .** called a
37410 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20   "soft" limit.  
37420 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f  It is advisory o
37430 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72  nly..**.** Prior
37440 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69   to SQLite versi
37450 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72  on 3.5.0, this r
37460 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73  outine only cons
37470 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f  trained the memo
37480 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20  ry.** allocated 
37490 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
374a0 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68  ad - the same th
374b0 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 68  read in which th
374c0 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75  is routine.** ru
374d0 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77  ns.  Beginning w
374e0 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69  ith SQLite versi
374f0 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f  on 3.5.0, the so
37500 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
37510 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61  .** applied to a
37520 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65 20  ll threads. The 
37530 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 20  value specified 
37540 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  for the soft hea
37550 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e  p limit.** is an
37560 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20   upper bound on 
37570 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79  the total memory
37580 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
37590 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a  all threads. In.
375a0 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  ** version 3.5.0
375b0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63   there is no mec
375c0 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74  hanism for limit
375d0 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73 61  ing the heap usa
375e0 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69  ge for.** indivi
375f0 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a  dual threads..**
37600 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
37610 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 31 7d 20 54  **.** {F16351} T
37620 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  he [sqlite3_soft
37630 5f 68 65 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20  _heap_limit(N)] 
37640 69 6e 74 65 72 66 61 63 65 20 70 6c 61 63 65 73  interface places
37650 20 61 20 73 6f 66 74 20 6c 69 6d 69 74 0a 2a 2a   a soft limit.**
37660 20 20 20 20 20 20 20 20 20 20 6f 66 20 4e 20 62            of N b
37670 79 74 65 73 20 6f 6e 20 74 68 65 20 61 6d 6f 75  ytes on the amou
37680 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  nt of heap memor
37690 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c  y that may be al
376a0 6c 6f 63 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  located.**      
376b0 20 20 20 20 75 73 69 6e 67 20 5b 73 71 6c 69 74      using [sqlit
376c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
376d0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
376e0 28 29 5d 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  ()] at any point
376f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
37700 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  time..**.** {F16
37710 33 35 32 7d 20 49 66 20 61 20 63 61 6c 6c 20 74  352} If a call t
37720 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
37730 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
37740 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 77 6f 75 6c  _realloc()] woul
37750 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  d.**          ca
37760 75 73 65 20 74 68 65 20 74 6f 74 61 6c 20 61 6d  use the total am
37770 6f 75 6e 74 20 6f 66 20 61 6c 6c 6f 63 61 74 65  ount of allocate
37780 64 20 6d 65 6d 6f 72 79 20 74 6f 20 65 78 63 65  d memory to exce
37790 65 64 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ed the.**       
377a0 20 20 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d     soft heap lim
377b0 69 74 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  it, then [sqlite
377c0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
377d0 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  ()] is invoked.*
377e0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 61 6e  *          in an
377f0 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 64 75   attempt to redu
37800 63 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 75 73  ce the memory us
37810 61 67 65 20 70 72 69 6f 72 20 74 6f 20 70 72 6f  age prior to pro
37820 63 65 65 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20  ceeding.**      
37830 20 20 20 20 77 69 74 68 20 74 68 65 20 6d 65 6d      with the mem
37840 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ory allocation a
37850 74 74 65 6d 70 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ttempt..**.** {F
37860 31 36 33 35 33 7d 20 43 61 6c 6c 73 20 74 6f 20  16353} Calls to 
37870 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
37880 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
37890 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 74  ealloc()] that t
378a0 72 69 67 67 65 72 0a 2a 2a 20 20 20 20 20 20 20  rigger.**       
378b0 20 20 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72     attempts to r
378c0 65 64 75 63 65 20 6d 65 6d 6f 72 79 20 75 73 61  educe memory usa
378d0 67 65 20 74 68 72 6f 75 67 68 20 74 68 65 20 73  ge through the s
378e0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a  oft heap limit.*
378f0 2a 20 20 20 20 20 20 20 20 20 20 6d 65 63 68 61  *          mecha
37900 6e 69 73 6d 20 63 6f 6e 74 69 6e 75 65 20 65 76  nism continue ev
37910 65 6e 20 69 66 20 74 68 65 20 61 74 74 65 6d 70  en if the attemp
37920 74 20 74 6f 20 72 65 64 75 63 65 20 6d 65 6d 6f  t to reduce memo
37930 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75  ry.**          u
37940 73 61 67 65 20 69 73 20 75 6e 73 75 63 63 65 73  sage is unsucces
37950 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  sful..**.** {F16
37960 33 35 34 7d 20 41 20 6e 65 67 61 74 69 76 65 20  354} A negative 
37970 6f 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f  or zero value fo
37980 72 20 4e 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f  r N in a call to
37990 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
379a0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
379b0 6c 69 6d 69 74 28 4e 29 5d 20 6d 65 61 6e 73 20  limit(N)] means 
379c0 74 68 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f  that there is no
379d0 20 73 6f 66 74 0a 2a 2a 20 20 20 20 20 20 20 20   soft.**        
379e0 20 20 68 65 61 70 20 6c 69 6d 69 74 20 61 6e 64    heap limit and
379f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
37a00 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c  e_memory()] will
37a10 20 6f 6e 6c 79 20 62 65 0a 2a 2a 20 20 20 20 20   only be.**     
37a20 20 20 20 20 20 63 61 6c 6c 65 64 20 77 68 65 6e       called when
37a30 20 6d 65 6d 6f 72 79 20 69 73 20 63 6f 6d 70 6c   memory is compl
37a40 65 74 65 6c 79 20 65 78 68 61 75 73 74 65 64 2e  etely exhausted.
37a50 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 35 7d 20  .**.** {F16355} 
37a60 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
37a70 65 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68  e for the soft h
37a80 65 61 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72  eap limit is zer
37a90 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 38  o..**.** {F16358
37aa0 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b  } Each call to [
37ab0 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
37ac0 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 6f 76 65 72  p_limit(N)] over
37ad0 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  rides the.**    
37ae0 20 20 20 20 20 20 76 61 6c 75 65 73 20 73 65 74        values set
37af0 20 62 79 20 61 6c 6c 20 70 72 69 6f 72 20 63 61   by all prior ca
37b00 6c 6c 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  lls..*/.void sql
37b10 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
37b20 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  imit(int);../*.*
37b30 2a 20 43 41 50 49 33 52 45 46 3a 20 20 45 78 74  * CAPI3REF:  Ext
37b40 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 41 62  ract Metadata Ab
37b50 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20  out A Column Of 
37b60 41 20 54 61 62 6c 65 20 7b 46 31 32 38 35 30 7d  A Table {F12850}
37b70 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
37b80 69 6e 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6d  ine.** returns m
37b90 65 74 61 2d 64 61 74 61 20 61 62 6f 75 74 20 61  eta-data about a
37ba0 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e   specific column
37bb0 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 20 64   of a specific d
37bc0 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65  atabase.** table
37bd0 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e   accessible usin
37be0 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  g the connection
37bf0 20 68 61 6e 64 6c 65 20 70 61 73 73 65 64 20 61   handle passed a
37c00 73 20 74 68 65 20 66 69 72 73 74 20 66 75 6e 63  s the first func
37c10 74 69 6f 6e 20 0a 2a 2a 20 61 72 67 75 6d 65 6e  tion .** argumen
37c20 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c  t..**.** The col
37c30 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65  umn is identifie
37c40 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c  d by the second,
37c50 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
37c60 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
37c70 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f  .** this functio
37c80 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  n. The second pa
37c90 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 68 65  rameter is eithe
37ca0 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  r the name of th
37cb0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69  e database.** (i
37cc0 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d  .e. "main", "tem
37cd0 70 22 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65  p" or an attache
37ce0 64 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74  d database) cont
37cf0 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69  aining the speci
37d00 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72  fied.** table or
37d10 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20 69 73 20   NULL. If it is 
37d20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61  NULL, then all a
37d30 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
37d40 73 20 61 72 65 20 73 65 61 72 63 68 65 64 0a 2a  s are searched.*
37d50 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20  * for the table 
37d60 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61  using the same a
37d70 6c 67 6f 72 69 74 68 6d 20 61 73 20 74 68 65 20  lgorithm as the 
37d80 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
37d90 75 73 65 73 20 74 6f 20 0a 2a 2a 20 72 65 73 6f  uses to .** reso
37da0 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64 20  lve unqualified 
37db0 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73  table references
37dc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72  ..**.** The thir
37dd0 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72  d and fourth par
37de0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20  ameters to this 
37df0 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65  function are the
37e00 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d   table and colum
37e10 6e 20 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68  n .** name of th
37e20 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e  e desired column
37e30 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  , respectively. 
37e40 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65  Neither of these
37e50 20 70 61 72 61 6d 65 74 65 72 73 20 0a 2a 2a 20   parameters .** 
37e60 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  may be NULL..**.
37e70 2a 2a 20 4d 65 74 61 20 69 6e 66 6f 72 6d 61 74  ** Meta informat
37e80 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 20  ion is returned 
37e90 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68  by writing to th
37ea0 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f  e memory locatio
37eb0 6e 73 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20  ns passed as.** 
37ec0 74 68 65 20 35 74 68 20 61 6e 64 20 73 75 62 73  the 5th and subs
37ed0 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72  equent parameter
37ee0 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  s to this functi
37ef0 6f 6e 2e 20 41 6e 79 20 6f 66 20 74 68 65 73 65  on. Any of these
37f00 20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6d   .** arguments m
37f10 61 79 20 62 65 20 4e 55 4c 4c 2c 20 69 6e 20 77  ay be NULL, in w
37f20 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63 6f  hich case the co
37f30 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d  rresponding elem
37f40 65 6e 74 20 6f 66 20 6d 65 74 61 20 0a 2a 2a 20  ent of meta .** 
37f50 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 6f  information is o
37f60 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 70  mitted..**.** <p
37f70 72 65 3e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72  re>.** Parameter
37f80 20 20 20 20 20 4f 75 74 70 75 74 20 54 79 70 65       Output Type
37f90 20 20 20 20 20 20 44 65 73 63 72 69 70 74 69 6f        Descriptio
37fa0 6e 0a 2a 2a 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  n.** -----------
37fb0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
37fc0 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 0a 2a 2a 20 20  --------.**.**  
37fd0 20 35 74 68 20 20 20 20 20 20 20 20 20 63 6f 6e   5th         con
37fe0 73 74 20 63 68 61 72 2a 20 20 20 20 20 20 44 61  st char*      Da
37ff0 74 61 20 74 79 70 65 0a 2a 2a 20 20 20 36 74 68  ta type.**   6th
38000 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 20 63           const c
38010 68 61 72 2a 20 20 20 20 20 20 4e 61 6d 65 20 6f  har*      Name o
38020 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 63 6f  f the default co
38030 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
38040 20 0a 2a 2a 20 20 20 37 74 68 20 20 20 20 20 20   .**   7th      
38050 20 20 20 69 6e 74 20 20 20 20 20 20 20 20 20 20     int          
38060 20 20 20 20 54 72 75 65 20 69 66 20 74 68 65 20      True if the 
38070 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54  column has a NOT
38080 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74   NULL constraint
38090 0a 2a 2a 20 20 20 38 74 68 20 20 20 20 20 20 20  .**   8th       
380a0 20 20 69 6e 74 20 20 20 20 20 20 20 20 20 20 20    int           
380b0 20 20 20 54 72 75 65 20 69 66 20 74 68 65 20 63     True if the c
380c0 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66  olumn is part of
380d0 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59   the PRIMARY KEY
380e0 0a 2a 2a 20 20 20 39 74 68 20 20 20 20 20 20 20  .**   9th       
380f0 20 20 69 6e 74 20 20 20 20 20 20 20 20 20 20 20    int           
38100 20 20 20 54 72 75 65 20 69 66 20 74 68 65 20 63     True if the c
38110 6f 6c 75 6d 6e 20 69 73 20 41 55 54 4f 49 4e 43  olumn is AUTOINC
38120 52 45 4d 45 4e 54 0a 2a 2a 20 3c 2f 70 72 65 3e  REMENT.** </pre>
38130 0a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65  .**.**.** The me
38140 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  mory pointed to 
38150 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72  by the character
38160 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
38170 65 64 20 66 6f 72 20 74 68 65 20 0a 2a 2a 20 64  ed for the .** d
38180 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20  eclaration type 
38190 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  and collation se
381a0 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20  quence is valid 
381b0 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e  only until the n
381c0 65 78 74 20 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  ext .** call to 
381d0 61 6e 79 20 73 71 6c 69 74 65 20 41 50 49 20 66  any sqlite API f
381e0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  unction..**.** I
381f0 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  f the specified 
38200 74 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c  table is actuall
38210 79 20 61 20 76 69 65 77 2c 20 74 68 65 6e 20 61  y a view, then a
38220 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
38230 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ned..**.** If th
38240 65 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75  e specified colu
38250 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20 22  mn is "rowid", "
38260 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f  oid" or "_rowid_
38270 22 20 61 6e 64 20 61 6e 20 0a 2a 2a 20 49 4e 54  " and an .** INT
38280 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
38290 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e   column has been
382a0 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
382b0 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  ared, then the o
382c0 75 74 70 75 74 20 0a 2a 2a 20 70 61 72 61 6d 65  utput .** parame
382d0 74 65 72 73 20 61 72 65 20 73 65 74 20 66 6f 72  ters are set for
382e0 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c 79 20   the explicitly 
382f0 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e  declared column.
38300 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a   If there is no.
38310 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  ** explicitly de
38320 63 6c 61 72 65 64 20 49 50 4b 20 63 6f 6c 75 6d  clared IPK colum
38330 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70  n, then the outp
38340 75 74 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  ut parameters ar
38350 65 20 73 65 74 20 61 73 20 0a 2a 2a 20 66 6f 6c  e set as .** fol
38360 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65  lows:.**.** <pre
38370 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79  >.**     data ty
38380 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a  pe: "INTEGER".**
38390 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73       collation s
383a0 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59  equence: "BINARY
383b0 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c  ".**     not nul
383c0 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d  l: 0.**     prim
383d0 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20  ary key: 1.**   
383e0 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74    auto increment
383f0 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a  : 0.** </pre>.**
38400 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
38410 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f  n may load one o
38420 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66  r more schemas f
38430 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c  rom database fil
38440 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72  es. If an.** err
38450 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
38460 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f   this process, o
38470 72 20 69 66 20 74 68 65 20 72 65 71 75 65 73 74  r if the request
38480 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  ed table or colu
38490 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20  mn.** cannot be 
384a0 66 6f 75 6e 64 2c 20 61 6e 20 53 51 4c 49 54 45  found, an SQLITE
384b0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
384c0 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65  eturned and an e
384d0 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20  rror message.** 
384e0 6c 65 66 74 20 69 6e 20 74 68 65 20 64 61 74 61  left in the data
384f0 62 61 73 65 20 68 61 6e 64 6c 65 20 28 74 6f 20  base handle (to 
38500 62 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69  be retrieved usi
38510 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  ng sqlite3_errms
38520 67 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  g())..**.** This
38530 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61   API is only ava
38540 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
38550 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
38560 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
38570 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
38580 55 4d 4e 5f 4d 45 54 41 44 41 54 41 20 70 72 65  UMN_METADATA pre
38590 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
385a0 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74   defined..*/.int
385b0 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63   sqlite3_table_c
385c0 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a  olumn_metadata(.
385d0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
385e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
385f0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64   Connection hand
38600 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
38610 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20  ar *zDbName,    
38620 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
38630 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a  name or NULL */.
38640 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54    const char *zT
38650 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a  ableName,     /*
38660 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20   Table name */. 
38670 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f   const char *zCo
38680 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20  lumnName,    /* 
38690 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20  Column name */. 
386a0 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a   char const **pz
386b0 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20  DataType,    /* 
386c0 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64  OUTPUT: Declared
386d0 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20   data type */.  
386e0 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43  char const **pzC
386f0 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f  ollSeq,     /* O
38700 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e  UTPUT: Collation
38710 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a   sequence name *
38720 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c  /.  int *pNotNul
38730 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  l,              
38740 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
38750 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73  if NOT NULL cons
38760 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f  traint exists */
38770 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79  .  int *pPrimary
38780 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Key,           /
38790 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
387a0 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66  f column part of
387b0 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41   PK */.  int *pA
387c0 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20  utoinc          
387d0 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
387e0 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69  True if column i
387f0 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74  s auto-increment
38800 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
38810 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20  PI3REF: Load An 
38820 45 78 74 65 6e 73 69 6f 6e 20 7b 46 31 32 36 30  Extension {F1260
38830 30 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30 31  0}.**.** {F12601
38840 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f  } The sqlite3_lo
38850 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
38860 6e 74 65 72 66 61 63 65 0a 2a 2a 20 61 74 74 65  nterface.** atte
38870 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 20  mpts to load an 
38880 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e  SQLite extension
38890 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e   library contain
388a0 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 0a 2a  ed in the file.*
388b0 2a 20 7a 46 69 6c 65 2e 20 7b 46 31 32 36 30 32  * zFile. {F12602
388c0 7d 20 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e  } The entry poin
388d0 74 20 69 73 20 7a 50 72 6f 63 2e 20 7b 46 31 32  t is zProc. {F12
388e0 36 30 33 7d 20 7a 50 72 6f 63 20 6d 61 79 20 62  603} zProc may b
388f0 65 20 30 0a 2a 2a 20 69 6e 20 77 68 69 63 68 20  e 0.** in which 
38900 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66  case the name of
38910 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74   the entry point
38920 20 64 65 66 61 75 6c 74 73 0a 2a 2a 20 74 6f 20   defaults.** to 
38930 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73 69  "sqlite3_extensi
38940 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20  on_init"..**.** 
38950 7b 46 31 32 36 30 34 7d 20 54 68 65 20 73 71 6c  {F12604}