/ Hex Artifact Content
Login

Artifact 6a80d00621a43271f01c77eb42bbf57e0f52051b:


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 35 33 20 32 30 30 38 2f 30  n,v 1.353 2008/0
05f0: 36 2f 32 33 20 31 31 3a 32 33 3a 31 34 20 6d 69  6/23 11:23:14 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 42 4c 4f 42 20 68 61 6e  e] all [BLOB han
1ee0: 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74 65 64  dles] associated
1ef0: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 73 71   with.** the [sq
1f00: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
1f10: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
1f20: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
1f30: 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65 20 5b 73  bject..** The [s
1f40: 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
1f50: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61  ()] interface ca
1f60: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 6f 63  n be used to loc
1f70: 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70 72 65 70  ate all.** [prep
1f80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
1f90: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1fa0: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
1fb0: 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64 65 73 69  nection] if desi
1fc0: 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63 61 6c 20  red..** Typical 
1fd0: 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f 6f 6b 20  code might look 
1fe0: 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
1ff0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
2000: 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  e>.** sqlite3_st
2010: 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a 20 77 68  mt *pStmt;.** wh
2020: 69 6c 65 28 20 28 70 53 74 6d 74 20 3d 20 73 71  ile( (pStmt = sq
2030: 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
2040: 64 62 2c 20 30 29 29 21 3d 30 20 29 7b 0a 2a 2a  db, 0))!=0 ){.**
2050: 20 26 6e 62 73 70 3b 20 20 20 73 71 6c 69 74 65   &nbsp;   sqlite
2060: 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53 74 6d 74  3_finalize(pStmt
2070: 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f 70 72 65  );.** }.** </pre
2080: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
2090: 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  *.** If [sqlite3
20a0: 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76  _close()] is inv
20b0: 6f 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61  oked while a tra
20c0: 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nsaction is open
20d0: 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63  ,.** the transac
20e0: 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69  tion is automati
20f0: 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
2100: 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  k..**.** INVARIA
2110: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30  NTS:.**.** {F120
2120: 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  11} The [sqlite3
2130: 5f 63 6c 6f 73 65 28 29 5d 20 69 6e 74 65 72 66  _close()] interf
2140: 61 63 65 20 64 65 73 74 72 6f 79 73 20 61 6e 20  ace destroys an 
2150: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2160: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c  .**          all
2170: 6f 63 61 74 65 64 20 62 79 20 61 20 70 72 69 6f  ocated by a prio
2180: 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  r call to [sqlit
2190: 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 20  e3_open()],.**  
21a0: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
21b0: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b  _open16()], or [
21c0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21d0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31  )]..**.** {F1201
21e0: 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
21f0: 63 6c 6f 73 65 28 29 5d 20 66 75 6e 63 74 69 6f  close()] functio
2200: 6e 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 20 6d  n releases all m
2210: 65 6d 6f 72 79 20 75 73 65 64 20 62 79 20 74 68  emory used by th
2220: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
2230: 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 63 6c 6f  nnection and clo
2240: 73 65 73 20 61 6c 6c 20 6f 70 65 6e 20 66 69 6c  ses all open fil
2250: 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31  es..**.** {F1201
2260: 33 7d 20 49 66 20 74 68 65 20 64 61 74 61 62 61  3} If the databa
2270: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6f  se connection co
2280: 6e 74 61 69 6e 73 20 5b 70 72 65 70 61 72 65 64  ntains [prepared
2290: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 74 68 61   statements] tha
22a0: 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61  t.**          ha
22b0: 76 65 20 6e 6f 74 20 62 65 65 6e 20 5b 73 71 6c  ve not been [sql
22c0: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
22d0: 66 69 6e 61 6c 69 7a 65 64 5d 2c 0a 2a 2a 20 20  finalized],.**  
22e0: 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71          then [sq
22f0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 72  lite3_close()] r
2300: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
2310: 55 53 59 5d 20 61 6e 64 20 6c 65 61 76 65 73 0a  USY] and leaves.
2320: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2330: 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 2e  connection open.
2340: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 30 31 34 7d 20  .**.** {F12014} 
2350: 50 61 73 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  Passing sqlite3_
2360: 63 6c 6f 73 65 28 29 20 61 20 4e 55 4c 4c 20 70  close() a NULL p
2370: 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d  ointer is a harm
2380: 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
2390: 2a 20 7b 46 31 32 30 31 39 7d 20 57 68 65 6e 20  * {F12019} When 
23a0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
23b0: 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  ] is invoked on 
23c0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
23d0: 65 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20 20 20  ection].**      
23e0: 20 20 20 20 74 68 61 74 20 68 61 73 20 61 20 70      that has a p
23f0: 65 6e 64 69 6e 67 20 74 72 61 6e 73 61 63 74 69  ending transacti
2400: 6f 6e 2c 20 74 68 65 20 74 72 61 6e 73 61 63 74  on, the transact
2410: 69 6f 6e 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20  ion shall be.** 
2420: 20 20 20 20 20 20 20 20 20 72 6f 6c 6c 65 64 20           rolled 
2430: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49  back..**.** LIMI
2440: 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  TATIONS:.**.** {
2450: 55 31 32 30 31 35 7d 20 54 68 65 20 70 61 72 61  U12015} The para
2460: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2470: 33 5f 63 6c 6f 73 65 28 29 5d 20 6d 75 73 74 20  3_close()] must 
2480: 62 65 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  be an [sqlite3] 
2490: 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20 20 20  object.**       
24a0: 20 20 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69     pointer previ
24b0: 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
24c0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  rom [sqlite3_ope
24d0: 6e 28 29 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 20  n()] or the.**  
24e0: 20 20 20 20 20 20 20 20 65 71 75 69 76 61 6c 65          equivale
24f0: 6e 74 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  nt, or NULL..**.
2500: 2a 2a 20 7b 55 31 32 30 31 36 7d 20 54 68 65 20  ** {U12016} The 
2510: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
2520: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 6d  lite3_close()] m
2530: 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65  ust not have bee
2540: 6e 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20  n previously.** 
2550: 20 20 20 20 20 20 20 20 20 63 6c 6f 73 65 64 2e           closed.
2560: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2570: 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a 29  close(sqlite3 *)
2580: 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70  ;../*.** The typ
2590: 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b  e for a callback
25a0: 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
25b0: 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64  is is legacy and
25c0: 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74   deprecated.  It
25d0: 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72   is included for
25e0: 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63   historical.** c
25f0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64  ompatibility and
2600: 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74   is not document
2610: 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69  ed..*/.typedef i
2620: 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c  nt (*sqlite3_cal
2630: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74  lback)(void*,int
2640: 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29  ,char**, char**)
2650: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2660: 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72  F: One-Step Quer
2670: 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65  y Execution Inte
2680: 72 66 61 63 65 20 7b 46 31 32 31 30 30 7d 0a 2a  rface {F12100}.*
2690: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
26a0: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
26b0: 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e  e is a convenien
26c0: 74 20 77 61 79 20 6f 66 20 72 75 6e 6e 69 6e 67  t way of running
26d0: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
26e0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 77  SQL statements w
26f0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
2700: 20 77 72 69 74 65 20 61 20 6c 6f 74 20 6f 66 20   write a lot of 
2710: 43 20 63 6f 64 65 2e 20 20 54 68 65 20 55 54 46  C code.  The UTF
2720: 2d 38 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 53 51  -8 encoded.** SQ
2730: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
2740: 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
2750: 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2760: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
2770: 65 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 74 61  ec()..** The sta
2780: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c  tements are eval
2790: 75 61 74 65 64 20 6f 6e 65 20 62 79 20 6f 6e 65  uated one by one
27a0: 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 61 6e   until either an
27b0: 20 65 72 72 6f 72 20 6f 72 0a 2a 2a 20 61 6e 20   error or.** an 
27c0: 69 6e 74 65 72 72 75 70 74 20 69 73 20 65 6e 63  interrupt is enc
27d0: 6f 75 6e 74 65 72 65 64 2c 20 6f 72 20 75 6e 74  ountered, or unt
27e0: 69 6c 20 74 68 65 79 20 61 72 65 20 61 6c 6c 20  il they are all 
27f0: 64 6f 6e 65 2e 20 20 54 68 65 20 33 72 64 20 70  done.  The 3rd p
2800: 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 61  arameter.** is a
2810: 6e 20 6f 70 74 69 6f 6e 61 6c 20 63 61 6c 6c 62  n optional callb
2820: 61 63 6b 20 74 68 61 74 20 69 73 20 69 6e 76 6f  ack that is invo
2830: 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  ked once for eac
2840: 68 20 72 6f 77 20 6f 66 20 61 6e 79 20 71 75 65  h row of any que
2850: 72 79 0a 2a 2a 20 72 65 73 75 6c 74 73 20 70 72  ry.** results pr
2860: 6f 64 75 63 65 64 20 62 79 20 74 68 65 20 53 51  oduced by the SQ
2870: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54  L statements.  T
2880: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
2890: 20 74 65 6c 6c 73 20 77 68 65 72 65 0a 2a 2a 20   tells where.** 
28a0: 74 6f 20 77 72 69 74 65 20 61 6e 79 20 65 72 72  to write any err
28b0: 6f 72 20 6d 65 73 73 61 67 65 73 2e 0a 2a 2a 0a  or messages..**.
28c0: 2a 2a 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73  ** The error mes
28d0: 73 61 67 65 20 70 61 73 73 65 64 20 62 61 63 6b  sage passed back
28e0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
28f0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 68 65   parameter is he
2900: 6c 64 0a 2a 2a 20 69 6e 20 6d 65 6d 6f 72 79 20  ld.** in memory 
2910: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2920: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
2930: 2e 20 20 54 6f 20 61 76 6f 69 64 20 61 20 6d 65  .  To avoid a me
2940: 6d 6f 72 79 20 6c 65 61 6b 2c 0a 2a 2a 20 74 68  mory leak,.** th
2950: 65 20 63 61 6c 6c 69 6e 67 20 61 70 70 6c 69 63  e calling applic
2960: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 63 61 6c  ation should cal
2970: 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
2980: 29 5d 20 6f 6e 20 61 6e 79 20 65 72 72 6f 72 0a  )] on any error.
2990: 2a 2a 20 6d 65 73 73 61 67 65 20 72 65 74 75 72  ** message retur
29a0: 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 20  ned through the 
29b0: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 77 68  5th parameter wh
29c0: 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  en it has finish
29d0: 65 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  ed using.** the 
29e0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
29f0: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
2a00: 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
2a10: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69   2nd parameter i
2a20: 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70  s NULL or an emp
2a30: 74 79 20 73 74 72 69 6e 67 0a 2a 2a 20 6f 72 20  ty string.** or 
2a40: 61 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  a string contain
2a50: 69 6e 67 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ing only whitesp
2a60: 61 63 65 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  ace and comments
2a70: 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 0a 2a 2a  , then no SQL.**
2a80: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
2a90: 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68  evaluated and th
2aa0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f  e database is no
2ab0: 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a  t changed..**.**
2ac0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
2ad0: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
2ae0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20   implemented in 
2af0: 74 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71 6c  terms of.** [sql
2b00: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2b10: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
2b20: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
2b30: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
2b40: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
2b50: 78 65 63 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  xec() routine do
2b60: 65 73 20 6e 6f 74 68 69 6e 67 20 74 6f 20 74 68  es nothing to th
2b70: 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74 20  e database that 
2b80: 63 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65 0a 2a  cannot be done.*
2b90: 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
2ba0: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
2bb0: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61  lite3_step()], a
2bc0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  nd [sqlite3_fina
2bd0: 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  lize()]..**.** I
2be0: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2bf0: 20 7b 46 31 32 31 30 31 7d 20 41 20 73 75 63 63   {F12101} A succ
2c00: 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
2c10: 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78  n of [sqlite3_ex
2c20: 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 0a 2a  ec(D,S,C,A,E)].*
2c30: 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c  *          shall
2c40: 20 65 76 61 6c 75 61 74 65 20 61 6c 6c 20 6f 66   evaluate all of
2c50: 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   the UTF-8 encod
2c60: 65 64 2c 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  ed, semicolon-se
2c70: 70 61 72 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  parated.**      
2c80: 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e      SQL statemen
2c90: 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
2ca0: 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
2cb0: 20 53 20 77 69 74 68 69 6e 20 74 68 65 0a 2a 2a   S within the.**
2cc0: 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78            contex
2cd0: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
2ce0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
2cf0: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30 32 7d  ..**.** {F12102}
2d00: 20 49 66 20 74 68 65 20 53 20 70 61 72 61 6d 65   If the S parame
2d10: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
2d20: 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d  exec(D,S,C,A,E)]
2d30: 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a   is NULL then.**
2d40: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61 63            the ac
2d50: 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 69 6e 74  tions of the int
2d60: 65 72 66 61 63 65 20 73 68 61 6c 6c 20 62 65 20  erface shall be 
2d70: 74 68 65 20 73 61 6d 65 20 61 73 20 69 66 20 74  the same as if t
2d80: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  he.**          S
2d90: 20 70 61 72 61 6d 65 74 65 72 20 77 65 72 65 20   parameter were 
2da0: 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e  an empty string.
2db0: 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30 34 7d 20  .**.** {F12104} 
2dc0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
2dd0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   of [sqlite3_exe
2de0: 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 20 5b 53  c()] shall be [S
2df0: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61 6c 6c  QLITE_OK] if all
2e00: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
2e10: 20 73 74 61 74 65 6d 65 6e 74 73 20 72 75 6e 20   statements run 
2e20: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61 6e 64  successfully and
2e30: 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
2e40: 2a 2a 0a 2a 2a 20 7b 46 31 32 31 30 35 7d 20 54  **.** {F12105} T
2e50: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
2e60: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  of [sqlite3_exec
2e70: 28 29 5d 20 73 68 61 6c 6c 20 62 65 20 61 6e 20  ()] shall be an 
2e80: 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 20  appropriate.**  
2e90: 20 20 20 20 20 20 20 20 6e 6f 6e 2d 7a 65 72 6f          non-zero
2ea0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
2eb0: 20 61 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65   any SQL stateme
2ec0: 6e 74 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  nt fails..**.** 
2ed0: 7b 46 31 32 31 30 37 7d 20 49 66 20 6f 6e 65 20  {F12107} If one 
2ee0: 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 53  or more of the S
2ef0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 68 61  QL statements ha
2f00: 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  nded to [sqlite3
2f10: 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20  _exec()].**     
2f20: 20 20 20 20 20 72 65 74 75 72 6e 20 72 65 73 75       return resu
2f30: 6c 74 73 20 61 6e 64 20 74 68 65 20 33 72 64 20  lts and the 3rd 
2f40: 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 74  parameter is not
2f50: 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a 2a 2a 20 20   NULL, then.**  
2f60: 20 20 20 20 20 20 20 20 74 68 65 20 63 61 6c 6c          the call
2f70: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 70  back function sp
2f80: 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 33  ecified by the 3
2f90: 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 68 61  rd parameter sha
2fa0: 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20  ll be.**        
2fb0: 20 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66    invoked once f
2fc0: 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 72  or each row of r
2fd0: 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  esult..**.** {F1
2fe0: 32 31 31 30 7d 20 49 66 20 74 68 65 20 63 61 6c  2110} If the cal
2ff0: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20  lback returns a 
3000: 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c 75 65 20 74  non-zero value t
3010: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  hen [sqlite3_exe
3020: 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  c()].**         
3030: 20 73 68 61 6c 6c 20 61 62 6f 72 74 20 74 68 65   shall abort the
3040: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
3050: 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 65  t is currently e
3060: 76 61 6c 75 61 74 69 6e 67 2c 0a 2a 2a 20 20 20  valuating,.**   
3070: 20 20 20 20 20 20 20 73 6b 69 70 20 61 6c 6c 20         skip all 
3080: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
3090: 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 72  tatements, and r
30a0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 41 42  eturn [SQLITE_AB
30b0: 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ORT]..**.** {F12
30c0: 31 31 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  113} The [sqlite
30d0: 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e  3_exec()] routin
30e0: 65 20 73 68 61 6c 6c 20 70 61 73 73 20 69 74 73  e shall pass its
30f0: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
3100: 68 72 6f 75 67 68 0a 2a 2a 20 20 20 20 20 20 20  hrough.**       
3110: 20 20 20 61 73 20 74 68 65 20 31 73 74 20 70 61     as the 1st pa
3120: 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 63  rameter of the c
3130: 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b  allback..**.** {
3140: 46 31 32 31 31 36 7d 20 54 68 65 20 5b 73 71 6c  F12116} The [sql
3150: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75  ite3_exec()] rou
3160: 74 69 6e 65 20 73 65 74 73 20 74 68 65 20 32 6e  tine sets the 2n
3170: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69  d parameter of i
3180: 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  ts.**          c
3190: 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 74 68  allback to be th
31a0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
31b0: 6d 6e 73 20 69 6e 20 74 68 65 20 63 75 72 72 65  mns in the curre
31c0: 6e 74 20 72 6f 77 20 6f 66 0a 2a 2a 20 20 20 20  nt row of.**    
31d0: 20 20 20 20 20 20 72 65 73 75 6c 74 2e 0a 2a 2a        result..**
31e0: 0a 2a 2a 20 7b 46 31 32 31 31 39 7d 20 54 68 65  .** {F12119} The
31f0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3200: 5d 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 74  ] routine sets t
3210: 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
3220: 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20   of its.**      
3230: 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20      callback to 
3240: 62 65 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  be an array of p
3250: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3260: 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a  gs holding the.*
3270: 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
3280: 73 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  s for each colum
3290: 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
32a0: 20 72 65 73 75 6c 74 20 73 65 74 20 72 6f 77 20   result set row 
32b0: 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  as.**          o
32c0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
32d0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
32e0: 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  t()]..**.** {F12
32f0: 31 32 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  122} The [sqlite
3300: 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e  3_exec()] routin
3310: 65 20 73 65 74 73 20 74 68 65 20 34 74 68 20 70  e sets the 4th p
3320: 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a  arameter of its.
3330: 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
3340: 62 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72  back to be an ar
3350: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
3360: 74 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69  to strings holdi
3370: 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ng the.**       
3380: 20 20 20 6e 61 6d 65 73 20 6f 66 20 72 65 73 75     names of resu
3390: 6c 74 20 63 6f 6c 75 6d 6e 73 20 61 73 20 6f 62  lt columns as ob
33a0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
33b0: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
33c0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 31  ()]..**.** {F121
33d0: 32 35 7d 20 49 66 20 74 68 65 20 33 72 64 20 70  25} If the 3rd p
33e0: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
33f0: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20  ite3_exec()] is 
3400: 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  NULL then.**    
3410: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
3420: 78 65 63 28 29 5d 20 6e 65 76 65 72 20 69 6e 76  xec()] never inv
3430: 6f 6b 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 2e  okes a callback.
3440: 20 20 41 6c 6c 20 71 75 65 72 79 0a 2a 2a 20 20    All query.**  
3450: 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 73 20          results 
3460: 61 72 65 20 73 69 6c 65 6e 74 6c 79 20 64 69 73  are silently dis
3470: 63 61 72 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  carded..**.** {F
3480: 31 32 31 33 31 7d 20 49 66 20 61 6e 20 65 72 72  12131} If an err
3490: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20  or occurs while 
34a0: 70 61 72 73 69 6e 67 20 6f 72 20 65 76 61 6c 75  parsing or evalu
34b0: 61 74 69 6e 67 20 61 6e 79 20 6f 66 20 74 68 65  ating any of the
34c0: 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20   SQL.**         
34d0: 20 68 61 6e 64 65 64 20 69 6e 20 74 68 65 20 53   handed in the S
34e0: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73   parameter of [s
34f0: 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c  qlite3_exec(D,S,
3500: 43 2c 41 2c 45 29 5d 20 61 6e 64 20 69 66 0a 2a  C,A,E)] and if.*
3510: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 45  *          the E
3520: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f   parameter is no
3530: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 73 71  t NULL, then [sq
3540: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68  lite3_exec()] sh
3550: 61 6c 6c 20 73 74 6f 72 65 0a 2a 2a 20 20 20 20  all store.**    
3560: 20 20 20 20 20 20 69 6e 20 2a 45 20 61 6e 20 61        in *E an a
3570: 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
3580: 20 6d 65 73 73 61 67 65 20 77 72 69 74 74 65 6e   message written
3590: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
35a0: 61 69 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  ained.**        
35b0: 20 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f    from [sqlite3_
35c0: 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a  malloc()]..**.**
35d0: 20 7b 46 31 32 31 33 34 7d 20 54 68 65 20 5b 73   {F12134} The [s
35e0: 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c  qlite3_exec(D,S,
35f0: 43 2c 41 2c 45 29 5d 20 72 6f 75 74 69 6e 65 20  C,A,E)] routine 
3600: 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 76 61  shall set the va
3610: 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  lue of.**       
3620: 20 20 20 2a 45 20 74 6f 20 4e 55 4c 4c 20 69 66     *E to NULL if
3630: 20 45 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61   E is not NULL a
3640: 6e 64 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  nd there are no 
3650: 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46  errors..**.** {F
3660: 31 32 31 33 37 7d 20 54 68 65 20 5b 73 71 6c 69  12137} The [sqli
3670: 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41  te3_exec(D,S,C,A
3680: 2c 45 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68  ,E)] function sh
3690: 61 6c 6c 20 73 65 74 20 74 68 65 20 5b 65 72 72  all set the [err
36a0: 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 20 20 20 20  or code].**     
36b0: 20 20 20 20 20 61 6e 64 20 6d 65 73 73 61 67 65       and message
36c0: 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20   accessible via 
36d0: 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
36e0: 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
36f0: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
3700: 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
3710: 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a  3_errmsg16()]..*
3720: 2a 0a 2a 2a 20 7b 46 31 32 31 33 38 7d 20 49 66  *.** {F12138} If
3730: 20 74 68 65 20 53 20 70 61 72 61 6d 65 74 65 72   the S parameter
3740: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
3750: 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 69 73  c(D,S,C,A,E)] is
3760: 20 4e 55 4c 4c 20 6f 72 20 61 6e 0a 2a 2a 20 20   NULL or an.**  
3770: 20 20 20 20 20 20 20 20 65 6d 70 74 79 20 73 74          empty st
3780: 72 69 6e 67 20 6f 72 20 63 6f 6e 74 61 69 6e 73  ring or contains
3790: 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72 20 74   nothing other t
37a0: 68 61 6e 20 77 68 69 74 65 73 70 61 63 65 2c 20  han whitespace, 
37b0: 63 6f 6d 6d 65 6e 74 73 2c 0a 2a 2a 20 20 20 20  comments,.**    
37c0: 20 20 20 20 20 20 61 6e 64 2f 6f 72 20 73 65 6d        and/or sem
37d0: 69 63 6f 6c 6f 6e 73 2c 20 74 68 65 6e 20 72 65  icolons, then re
37e0: 73 75 6c 74 73 20 6f 66 20 5b 73 71 6c 69 74 65  sults of [sqlite
37f0: 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a  3_errcode()],.**
3800: 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
3810: 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e  e3_errmsg()], an
3820: 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d [sqlite3_errms
3830: 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  g16()].**       
3840: 20 20 20 73 68 61 6c 6c 20 72 65 73 65 74 20 74     shall reset t
3850: 6f 20 69 6e 64 69 63 61 74 65 20 6e 6f 20 65 72  o indicate no er
3860: 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 4c 49 4d 49  rors..**.** LIMI
3870: 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  TATIONS:.**.** {
3880: 55 31 32 31 34 31 7d 20 54 68 65 20 66 69 72 73  U12141} The firs
3890: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  t parameter to [
38a0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
38b0: 6d 75 73 74 20 62 65 20 61 6e 20 76 61 6c 69 64  must be an valid
38c0: 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20 20 20   and open.**    
38d0: 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
38e0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  connection]..**.
38f0: 2a 2a 20 7b 55 31 32 31 34 32 7d 20 54 68 65 20  ** {U12142} The 
3900: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3910: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  ion must not be 
3920: 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a 20  closed while.** 
3930: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
3940: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e  3_exec()] is run
3950: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 32  ning..**.** {U12
3960: 31 34 33 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67  143} The calling
3970: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
3980: 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 66 72   use [sqlite3_fr
3990: 65 65 28 29 5d 20 74 6f 20 66 72 65 65 0a 2a 2a  ee()] to free.**
39a0: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6d 65            the me
39b0: 6d 6f 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73  mory that *errms
39c0: 67 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  g is left pointi
39d0: 6e 67 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65  ng at once the e
39e0: 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rror.**         
39f0: 20 6d 65 73 73 61 67 65 20 69 73 20 6e 6f 20 6c   message is no l
3a00: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
3a10: 0a 2a 2a 20 7b 55 31 32 31 34 35 7d 20 54 68 65  .** {U12145} The
3a20: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
3a30: 65 78 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70  ext in the 2nd p
3a40: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
3a50: 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20  ite3_exec()].** 
3a60: 20 20 20 20 20 20 20 20 20 6d 75 73 74 20 72 65           must re
3a70: 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 77  main unchanged w
3a80: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65 78  hile [sqlite3_ex
3a90: 65 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  ec()] is running
3aa0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
3ab0: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
3ac0: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
3ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ae0: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
3af0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
3b00: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
3b10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b20: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
3b30: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
3b40: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
3b50: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3b60: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
3b70: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
3b80: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  void *,
3b90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ba0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bb0: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
3bc0: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
3bd0: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
3be0: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
3bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c00: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
3c10: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
3c20: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
3c30: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 46   Result Codes {F
3c40: 31 30 32 31 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52  10210}.** KEYWOR
3c50: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3c60: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3c70: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3c80: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3c90: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3ca0: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3cb0: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3cc0: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3cd0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3ce0: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3cf0: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3d00: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3d10: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3d20: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
3d30: 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  : [SQLITE_IOERR_
3d40: 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20  READ | extended 
3d50: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f  result codes].*/
3d60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3d70: 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20  OK           0  
3d80: 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72   /* Successful r
3d90: 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69  esult */./* begi
3da0: 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63  nning-of-error-c
3db0: 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  odes */.#define 
3dc0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20  SQLITE_ERROR    
3dd0: 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65      1   /* SQL e
3de0: 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20  rror or missing 
3df0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
3e00: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
3e10: 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49  NAL     2   /* I
3e20: 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72  nternal logic er
3e30: 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f  ror in SQLite */
3e40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3e50: 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20  PERM         3  
3e60: 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69   /* Access permi
3e70: 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ssion denied */.
3e80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
3e90: 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20  BORT        4   
3ea0: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74  /* Callback rout
3eb0: 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e  ine requested an
3ec0: 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e   abort */.#defin
3ed0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20  e SQLITE_BUSY   
3ee0: 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65        5   /* The
3ef0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
3f00: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
3f10: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
3f20: 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41  D       6   /* A
3f30: 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61   table in the da
3f40: 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64  tabase is locked
3f50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3f60: 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  TE_NOMEM        
3f70: 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28  7   /* A malloc(
3f80: 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66  ) failed */.#def
3f90: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
3fa0: 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41  NLY     8   /* A
3fb0: 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20  ttempt to write 
3fc0: 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62  a readonly datab
3fd0: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
3fe0: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20  QLITE_INTERRUPT 
3ff0: 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74     9   /* Operat
4000: 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62  ion terminated b
4010: 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  y sqlite3_interr
4020: 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20  upt()*/.#define 
4030: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20  SQLITE_IOERR    
4040: 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20     10   /* Some 
4050: 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f  kind of disk I/O
4060: 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20   error occurred 
4070: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4080: 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31  E_CORRUPT     11
4090: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
40a0: 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73  se disk image is
40b0: 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64   malformed */.#d
40c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
40d0: 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a  FOUND    12   /*
40e0: 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c 65   NOT USED. Table
40f0: 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 66   or record not f
4100: 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ound */.#define 
4110: 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20  SQLITE_FULL     
4120: 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72     13   /* Inser
4130: 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61  tion failed beca
4140: 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20  use database is 
4150: 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  full */.#define 
4160: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
4170: 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c     14   /* Unabl
4180: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
4190: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
41b0: 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f  OTOCOL    15   /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 61  * NOT USED. Data
41d0: 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63  base lock protoc
41e0: 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ol error */.#def
41f0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59  ine SQLITE_EMPTY
4200: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44         16   /* D
4210: 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79  atabase is empty
4220: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4230: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31  TE_SCHEMA      1
4240: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  7   /* The datab
4250: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
4260: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4270: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20  LITE_TOOBIG     
4280: 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20   18   /* String 
4290: 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20  or BLOB exceeds 
42a0: 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64  size limit */.#d
42b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
42c0: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a  STRAINT  19   /*
42d0: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f   Abort due to co
42e0: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
42f0: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  on */.#define SQ
4300: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20  LITE_MISMATCH   
4310: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79   20   /* Data ty
4320: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23  pe mismatch */.#
4330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
4340: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f  SUSE      21   /
4350: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69  * Library used i
4360: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64  ncorrectly */.#d
4370: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c  efine SQLITE_NOL
4380: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a  FS       22   /*
4390: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65   Uses OS feature
43a0: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20  s not supported 
43b0: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69  on host */.#defi
43c0: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20  ne SQLITE_AUTH  
43d0: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75        23   /* Au
43e0: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69  thorization deni
43f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4400: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20  LITE_FORMAT     
4410: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61   24   /* Auxilia
4420: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d  ry database form
4430: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  at error */.#def
4440: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45  ine SQLITE_RANGE
4450: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32         25   /* 2
4460: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
4470: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74  sqlite3_bind out
4480: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65   of range */.#de
4490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41  fine SQLITE_NOTA
44a0: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20  DB      26   /* 
44b0: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74  File opened that
44c0: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
44d0: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
44e0: 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20  ne SQLITE_ROW   
44f0: 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71        100  /* sq
4500: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4510: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61   another row rea
4520: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  dy */.#define SQ
4530: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20  LITE_DONE       
4540: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33   101  /* sqlite3
4550: 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69  _step() has fini
4560: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a  shed executing *
4570: 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f  /./* end-of-erro
4580: 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a  r-codes */../*.*
4590: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65  * CAPI3REF: Exte
45a0: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
45b0: 73 20 7b 46 31 30 32 32 30 7d 0a 2a 2a 20 4b 45  s {F10220}.** KE
45c0: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
45d0: 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65  d error code} {e
45e0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
45f0: 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  des}.** KEYWORDS
4600: 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : {extended resu
4610: 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64  lt code} {extend
4620: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d  ed result codes}
4630: 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65  .**.** In its de
4640: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
4650: 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20  ion, SQLite API 
4660: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
4670: 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65  one of 26 intege
4680: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20  r.** [SQLITE_OK 
4690: 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e  | result codes].
46a0: 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72    However, exper
46b0: 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20  ience has shown 
46c0: 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20  that many of.** 
46d0: 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64  these result cod
46e0: 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73  es are too coars
46f0: 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79  e-grained.  They
4700: 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20   do not provide 
4710: 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72  as.** much infor
4720: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f  mation about pro
4730: 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d  blems as program
4740: 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e  mers might like.
4750: 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74    In an effort t
4760: 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69  o.** address thi
4770: 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  s, newer version
4780: 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72  s of SQLite (ver
4790: 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c  sion 3.3.8 and l
47a0: 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a  ater) include.**
47b0: 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64   support for add
47c0: 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63  itional result c
47d0: 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64  odes that provid
47e0: 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20  e more detailed 
47f0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
4800: 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65  bout errors. The
4810: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4820: 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c   codes are enabl
4830: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
4840: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
4850: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
4860: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
4870: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
4880: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
4890: 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53  ()] API..**.** S
48a0: 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c  ome of the avail
48b0: 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65  able extended re
48c0: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c  sult codes are l
48d0: 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f  isted here..** O
48e0: 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20 74 68  ne may expect th
48f0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65  e number of exte
4900: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4910: 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64  s will be expand
4920: 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20  .** over time.  
4930: 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 75 73  Software that us
4940: 65 73 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  es extended resu
4950: 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20  lt codes should 
4960: 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65  expect.** to see
4970: 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65   new result code
4980: 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  s in future rele
4990: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
49a0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
49b0: 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20  _OK result code 
49c0: 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78  will never be ex
49d0: 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c  tended.  It will
49e0: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78   always.** be ex
49f0: 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  actly zero..**.*
4a00: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
4a10: 0a 2a 2a 20 7b 46 31 30 32 32 33 7d 20 54 68 65  .** {F10223} The
4a20: 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 66   symbolic name f
4a30: 6f 72 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72  or an extended r
4a40: 65 73 75 6c 74 20 63 6f 64 65 20 61 6c 77 61 79  esult code alway
4a50: 73 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20  s contains.**   
4a60: 20 20 20 20 20 20 20 61 20 72 65 6c 61 74 65 64         a related
4a70: 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20   primary result 
4a80: 63 6f 64 65 20 61 73 20 61 20 70 72 65 66 69 78  code as a prefix
4a90: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 32 32 34 7d  ..**.** {F10224}
4aa0: 20 50 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20   Primary result 
4ab0: 63 6f 64 65 20 6e 61 6d 65 73 20 63 6f 6e 74 61  code names conta
4ac0: 69 6e 20 61 20 73 69 6e 67 6c 65 20 22 5f 22 20  in a single "_" 
4ad0: 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 0a 2a 2a  character..**.**
4ae0: 20 7b 46 31 30 32 32 35 7d 20 45 78 74 65 6e 64   {F10225} Extend
4af0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6e  ed result code n
4b00: 61 6d 65 73 20 63 6f 6e 74 61 69 6e 20 74 77 6f  ames contain two
4b10: 20 6f 72 20 6d 6f 72 65 20 22 5f 22 20 63 68 61   or more "_" cha
4b20: 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b  racters..**.** {
4b30: 46 31 30 32 32 36 7d 20 54 68 65 20 6e 75 6d 65  F10226} The nume
4b40: 72 69 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20  ric value of an 
4b50: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4b60: 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 74 68  code contains th
4b70: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
4b80: 6d 65 72 69 63 20 76 61 6c 75 65 20 6f 66 20 69  meric value of i
4b90: 74 73 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ts corresponding
4ba0: 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74 20   primary result 
4bb0: 63 6f 64 65 20 69 6e 0a 2a 2a 20 20 20 20 20 20  code in.**      
4bc0: 20 20 20 20 69 74 73 20 6c 65 61 73 74 20 73 69      its least si
4bd0: 67 6e 69 66 69 63 61 6e 74 20 38 20 62 69 74 73  gnificant 8 bits
4be0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4bf0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
4c00: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4c10: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
4c20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4c30: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
4c40: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
4c50: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
4c60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4c70: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
4c80: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4c90: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
4ca0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4cb0: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
4cc0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4cd0: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
4ce0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4cf0: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
4d00: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4d10: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
4d20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4d30: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
4d40: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4d50: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
4d60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4d70: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
4d80: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4d90: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
4da0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4db0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
4dc0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4dd0: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
4de0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4df0: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
4e00: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e10: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
4e20: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4e30: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
4e40: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4e50: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
4e60: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4e70: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
4e80: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4e90: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
4ea0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4eb0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
4ec0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4ed0: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
4ee0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4ef0: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
4f00: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4f10: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
4f20: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4f30: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
4f40: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
4f50: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 0a 2f 2a 0a   | (14<<8))../*.
4f60: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
4f70: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
4f80: 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b 46 31 30   Operations {F10
4f90: 32 33 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  230}.**.** These
4fa0: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
4fb0: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
4fc0: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70   in the.** 3rd p
4fd0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
4fe0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
4ff0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
5000: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20  d.** in the 4th 
5010: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5020: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66   xOpen method of
5030: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
5040: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  _vfs] object..*/
5050: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5060: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
5070: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
5080: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5090: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
50a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
50b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50c0: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
50d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
50e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50f0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
5100: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
5110: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5120: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
5130: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
5140: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5150: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
5160: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5170: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5180: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
5190: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
51a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
51b0: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
51c0: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
51d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
51e0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
51f0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
5200: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5210: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
5220: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
5230: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5240: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
5250: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
5260: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5270: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
5280: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
5290: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
52a0: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
52b0: 65 72 69 73 74 69 63 73 20 7b 46 31 30 32 34 30  eristics {F10240
52c0: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76  }.**.** The xDev
52d0: 69 63 65 43 61 70 61 62 69 6c 69 74 69 65 73 20  iceCapabilities 
52e0: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
52f0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5300: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
5310: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
5320: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
5330: 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a  r of the these.*
5340: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
5350: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
5360: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
5370: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
5380: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
5390: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
53a0: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
53b0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
53c0: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
53d0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
53e0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
53f0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
5400: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
5410: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
5420: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
5430: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
5440: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
5450: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
5460: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
5470: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
5480: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
5490: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
54a0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
54b0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
54c0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
54d0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
54e0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
54f0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
5500: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
5510: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
5520: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
5530: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
5540: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
5550: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
5560: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
5570: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
5580: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
5590: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
55a0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
55b0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
55c0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
55d0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
55e0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
55f0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
5600: 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e  ite()..*/.#defin
5610: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5620: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 30  TOMIC          0
5630: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
5640: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5650: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 30  TOMIC512       0
5660: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
5670: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5680: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 30  TOMIC1K        0
5690: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e  x00000004.#defin
56a0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
56b0: 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 30  TOMIC2K        0
56c0: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e  x00000008.#defin
56d0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
56e0: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 30  TOMIC4K        0
56f0: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
5700: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5710: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 30  TOMIC8K        0
5720: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
5730: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5740: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 30  TOMIC16K       0
5750: 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e  x00000040.#defin
5760: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5770: 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 30  TOMIC32K       0
5780: 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e  x00000080.#defin
5790: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
57a0: 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 30  TOMIC64K       0
57b0: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e  x00000100.#defin
57c0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
57d0: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 30  AFE_APPEND     0
57e0: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e  x00000200.#defin
57f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
5800: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 30  EQUENTIAL      0
5810: 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a  x00000400../*.**
5820: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
5830: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b  Locking Levels {
5840: 46 31 30 32 35 30 7d 0a 2a 2a 0a 2a 2a 20 53 51  F10250}.**.** SQ
5850: 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66  Lite uses one of
5860: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
5870: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
5880: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ond.** argument 
5890: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65  to calls it make
58a0: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29  s to the xLock()
58b0: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d   and xUnlock() m
58c0: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20  ethods.** of an 
58d0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
58e0: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ods] object..*/.
58f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5900: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20  OCK_NONE        
5910: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
5920: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20  TE_LOCK_SHARED  
5930: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
5940: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
5950: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66  RVED      2.#def
5960: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5970: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a  PENDING       3.
5980: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5990: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20  OCK_EXCLUSIVE   
59a0: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    4../*.** CAPI3
59b0: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61  REF: Synchroniza
59c0: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20  tion Type Flags 
59d0: 7b 46 31 30 32 36 30 7d 0a 2a 2a 0a 2a 2a 20 57  {F10260}.**.** W
59e0: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  hen SQLite invok
59f0: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d  es the xSync() m
5a00: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b  ethod of an.** [
5a10: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5a20: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73  ds] object it us
5a30: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  es a combination
5a40: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74   of.** these int
5a50: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
5a60: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
5a70: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
5a80: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
5a90: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
5aa0: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
5ab0: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
5ac0: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
5ad0: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
5ae0: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
5af0: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
5b00: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
5b10: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 54  ot be flushed. T
5b20: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
5b30: 4f 52 4d 41 4c 20 66 6c 61 67 20 6d 65 61 6e 73  ORMAL flag means
5b40: 0a 2a 2a 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61  .** to use norma
5b50: 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74  l fsync() semant
5b60: 69 63 73 2e 20 54 68 65 20 53 51 4c 49 54 45 5f  ics. The SQLITE_
5b70: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d  SYNC_FULL flag m
5b80: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
5b90: 61 63 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 75  ac OS-X style fu
5ba0: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
5bb0: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64  f fsync()..*/.#d
5bc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
5bd0: 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20  C_NORMAL        
5be0: 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0x00002.#define 
5bf0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
5c00: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5c10: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
5c20: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20  _SYNC_DATAONLY  
5c30: 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a      0x00010../*.
5c40: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
5c50: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46  Interface Open F
5c60: 69 6c 65 20 48 61 6e 64 6c 65 20 7b 46 31 31 31  ile Handle {F111
5c70: 31 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71  10}.**.** An [sq
5c80: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
5c90: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
5ca0: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68   open file in th
5cb0: 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61 63  e OS.** interfac
5cc0: 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69 76 69  e layer.  Indivi
5cd0: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
5ce0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
5cf0: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
5d00: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
5d10: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
5d20: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
5d30: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
5d40: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
5d50: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
5d60: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
5d70: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
5d80: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
5d90: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
5da0: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
5db0: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
5dc0: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
5dd0: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
5de0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
5df0: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
5e00: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
5e10: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
5e20: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
5e30: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
5e40: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
5e50: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
5e60: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
5e70: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
5e80: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
5e90: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
5ea0: 4f 62 6a 65 63 74 20 7b 46 31 31 31 32 30 7d 0a  Object {F11120}.
5eb0: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
5ec0: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
5ed0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70  sqlite3_vfs] xOp
5ee0: 65 6e 20 6d 65 74 68 6f 64 20 63 6f 6e 74 61 69  en method contai
5ef0: 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  ns a pointer to.
5f00: 2a 2a 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** an instance o
5f10: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 20 20  f this object.  
5f20: 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  This object defi
5f30: 6e 65 73 20 74 68 65 0a 2a 2a 20 6d 65 74 68 6f  nes the.** metho
5f40: 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f  ds used to perfo
5f50: 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61  rm various opera
5f60: 74 69 6f 6e 73 20 61 67 61 69 6e 73 74 20 74 68  tions against th
5f70: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2a 0a  e open file..**.
5f80: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
5f90: 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d  ument to xSync m
5fa0: 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51  ay be one of [SQ
5fb0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
5fc0: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
5fd0: 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65  SYNC_FULL].  The
5fe0: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73   first choice is
5ff0: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   the normal fsyn
6000: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  c()..** The seco
6010: 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d  nd choice is a M
6020: 61 63 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 75  ac OS-X style fu
6030: 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51  llsync.  The [SQ
6040: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
6050: 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20  LY].** flag may 
6060: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e  be ORed in to in
6070: 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79  dicate that only
6080: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65   the data of the
6090: 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74   file.** and not
60a0: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73   its inode needs
60b0: 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a   to be synced..*
60c0: 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72  *.** The integer
60d0: 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b   values to xLock
60e0: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
60f0: 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c   are one of.** <
6100: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
6110: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a  ITE_LOCK_NONE],.
6120: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6130: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
6140: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
6150: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a  CK_RESERVED],.**
6160: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
6170: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a  CK_PENDING], or.
6180: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6190: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e  LOCK_EXCLUSIVE].
61a0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f  .** </ul>.** xLo
61b0: 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74  ck() increases t
61c0: 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b  he lock. xUnlock
61d0: 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65  () decreases the
61e0: 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43   lock..** The xC
61f0: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
6200: 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73  () method checks
6210: 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74   whether any dat
6220: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
6230: 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74  ,.** either in t
6240: 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69  his process or i
6250: 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f  n some other pro
6260: 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67  cess, is holding
6270: 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20   a RESERVED,.** 
6280: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c  PENDING, or EXCL
6290: 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68  USIVE lock on th
62a0: 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75  e file.  It retu
62b0: 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73  rns true.** if s
62c0: 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74  uch a lock exist
62d0: 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65  s and false othe
62e0: 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rwise..**.** The
62f0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
6300: 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65  method is a gene
6310: 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68  ric interface th
6320: 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d  at allows custom
6330: 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  .** VFS implemen
6340: 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63  tations to direc
6350: 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f  tly control an o
6360: 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74  pen file using t
6370: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
6380: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
6390: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73  nterface.  The s
63a0: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d  econd "op" argum
63b0: 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74  ent is an.** int
63c0: 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68  eger opcode.  Th
63d0: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
63e0: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f   is a generic po
63f0: 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74  inter intended t
6400: 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20  o.** point to a 
6410: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d  structure that m
6420: 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d  ay contain argum
6430: 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e  ents or space in
6440: 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69   which to.** wri
6450: 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  te return values
6460: 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65  .  Potential use
6470: 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72  s for xFileContr
6480: 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a  ol() might be.**
6490: 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e   functions to en
64a0: 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f  able blocking lo
64b0: 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74  cks with timeout
64c0: 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  s, to change the
64d0: 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61  .** locking stra
64e0: 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c  tegy (for exampl
64f0: 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c  e to use dot-fil
6500: 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71  e locks), to inq
6510: 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68  uire.** about th
6520: 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f  e status of a lo
6530: 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20  ck, or to break 
6540: 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68  stale locks.  Th
6550: 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65  e SQLite.** core
6560: 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70   reserves all op
6570: 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20  codes less than 
6580: 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20  100 for its own 
6590: 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54  use..** A [SQLIT
65a0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
65b0: 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f  E | list of opco
65c0: 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31  des] less than 1
65d0: 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  00 is available.
65e0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
65f0: 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63   that define a c
6600: 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72  ustom xFileContr
6610: 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  ol method should
6620: 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20   use opcodes.** 
6630: 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30  greater than 100
6640: 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69   to avoid confli
6650: 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  cts..**.** The x
6660: 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74  SectorSize() met
6670: 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20  hod returns the 
6680: 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74  sector size of t
6690: 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  he.** device tha
66a0: 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20  t underlies the 
66b0: 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f  file.  The secto
66c0: 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a  r size is the.**
66d0: 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74   minimum write t
66e0: 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f  hat can be perfo
66f0: 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73  rmed without dis
6700: 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  turbing.** other
6710: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
6720: 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65  le.  The xDevice
6730: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28  Characteristics(
6740: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
6750: 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72  rns a bit vector
6760: 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61   describing beha
6770: 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20  viors of the.** 
6780: 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63  underlying devic
6790: 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
67a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
67b0: 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c  CAP_ATOMIC].** <
67c0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
67d0: 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20  P_ATOMIC512].** 
67e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
67f0: 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20  AP_ATOMIC1K].** 
6800: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6810: 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20  AP_ATOMIC2K].** 
6820: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6830: 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20  AP_ATOMIC4K].** 
6840: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6850: 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20  AP_ATOMIC8K].** 
6860: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6870: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a  AP_ATOMIC16K].**
6880: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
6890: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a  CAP_ATOMIC32K].*
68a0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
68b0: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a  OCAP_ATOMIC64K].
68c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
68d0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
68e0: 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  D].** <li> [SQLI
68f0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
6900: 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IAL].** </ul>.**
6910: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
6920: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
6930: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
6940: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
6950: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
6960: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
6970: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
6980: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
6990: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
69a0: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
69b0: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
69c0: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
69d0: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
69e0: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
69f0: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
6a00: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
6a10: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
6a20: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
6a30: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
6a40: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
6a50: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
6a60: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
6a70: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
6a80: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
6a90: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
6aa0: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
6ab0: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
6ac0: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
6ad0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6ae0: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
6af0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
6b00: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
6b10: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
6b20: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
6b30: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
6b40: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 74 79   xWrite()..*/.ty
6b50: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
6b60: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
6b70: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6b80: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
6b90: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
6ba0: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
6bb0: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
6bc0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
6bd0: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
6be0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
6bf0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
6c00: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
6c10: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
6c20: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
6c30: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
6c40: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
6c50: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
6c60: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
6c70: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
6c80: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
6c90: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
6ca0: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
6cb0: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
6cc0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
6cd0: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
6ce0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
6cf0: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
6d00: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
6d10: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
6d20: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
6d30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
6d40: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
6d50: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
6d60: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
6d70: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
6d80: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
6d90: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
6da0: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
6db0: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
6dc0: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
6dd0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
6de0: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
6df0: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
6e00: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
6e10: 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65  /* Additional me
6e20: 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64  thods may be add
6e30: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
6e40: 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  eases */.};../*.
6e50: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61  ** CAPI3REF: Sta
6e60: 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72  ndard File Contr
6e70: 6f 6c 20 4f 70 63 6f 64 65 73 20 7b 46 31 31 33  ol Opcodes {F113
6e80: 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  10}.**.** These 
6e90: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
6ea0: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f  s are opcodes fo
6eb0: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  r the xFileContr
6ec0: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  ol method.** of 
6ed0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
6ee0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
6ef0: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  and for the [sql
6f00: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
6f10: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  l()].** interfac
6f20: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  e..**.** The [SQ
6f30: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
6f40: 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  TATE] opcode is 
6f50: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69  used for debuggi
6f60: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ng.  This.** opc
6f70: 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78  ode causes the x
6f80: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
6f90: 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20  od to write the 
6fa0: 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66  current state of
6fb0: 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e  .** the lock (on
6fc0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  e of [SQLITE_LOC
6fd0: 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  K_NONE], [SQLITE
6fe0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
6ff0: 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  * [SQLITE_LOCK_R
7000: 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54  ESERVED], [SQLIT
7010: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
7020: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   or [SQLITE_LOCK
7030: 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20  _EXCLUSIVE]).** 
7040: 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  into an integer 
7050: 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72  that the pArg ar
7060: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f  gument points to
7070: 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74  . This capabilit
7080: 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72  y.** is used dur
7090: 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20  ing testing and 
70a0: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
70b0: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
70c0: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69  SQLITE_TEST.** i
70d0: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64  s defined..*/.#d
70e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
70f0: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20  TL_LOCKSTATE    
7100: 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      1../*.** CAP
7110: 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e  I3REF: Mutex Han
7120: 64 6c 65 20 7b 46 31 37 31 31 30 7d 0a 2a 2a 0a  dle {F17110}.**.
7130: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64  ** The mutex mod
7140: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74  ule within SQLit
7150: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74  e defines [sqlit
7160: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20  e3_mutex] to be 
7170: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74  an.** abstract t
7180: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20  ype for a mutex 
7190: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c  object.  The SQL
71a0: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c  ite core never l
71b0: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69  ooks.** at the i
71c0: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
71d0: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71  tation of an [sq
71e0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49  lite3_mutex].  I
71f0: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20  t only.** deals 
7200: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f  with pointers to
7210: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
7220: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  tex] object..**.
7230: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63  ** Mutexes are c
7240: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
7250: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
7260: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  c()]..*/.typedef
7270: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7280: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75  mutex sqlite3_mu
7290: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tex;../*.** CAPI
72a0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
72b0: 63 65 20 4f 62 6a 65 63 74 20 7b 46 31 31 31 34  ce Object {F1114
72c0: 30 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  0}.**.** An inst
72d0: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69  ance of the sqli
72e0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64  te3_vfs object d
72f0: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
7300: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20  face between.** 
7310: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
7320: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  and the underlyi
7330: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
7340: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a  tem.  The "vfs".
7350: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f  ** in the name o
7360: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61  f the object sta
7370: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c  nds for "virtual
7380: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a   file system"..*
7390: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
73a0: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
73b0: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
73c0: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
73d0: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
73e0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
73f0: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
7400: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
7410: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
7420: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
7430: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
7440: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
7450: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
7460: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
7470: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
7480: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
7490: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
74a0: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
74b0: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
74c0: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
74d0: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
74e0: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
74f0: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
7500: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
7510: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
7520: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
7530: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
7540: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
7550: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
7560: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
7570: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
7580: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
7590: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
75a0: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
75b0: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
75c0: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
75d0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
75e0: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
75f0: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
7600: 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ist..**.** The p
7610: 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68  Next field is th
7620: 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20  e only field in 
7630: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
7640: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61  ** structure tha
7650: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76  t SQLite will ev
7660: 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69  er modify.  SQLi
7670: 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63  te will only acc
7680: 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79  ess.** or modify
7690: 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c   this field whil
76a0: 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74  e holding a part
76b0: 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75  icular static mu
76c0: 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  tex..** The appl
76d0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
76e0: 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74  ever modify anyt
76f0: 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20  hing within the 
7700: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f  sqlite3_vfs.** o
7710: 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f  bject once the o
7720: 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72  bject has been r
7730: 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a  egistered..**.**
7740: 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64   The zName field
7750: 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20   holds the name 
7760: 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c  of the VFS modul
7770: 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73  e.  The name mus
7780: 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61  t.** be unique a
7790: 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f  cross all VFS mo
77a0: 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  dules..**.** {F1
77b0: 31 31 34 31 7d 20 53 51 4c 69 74 65 20 77 69 6c  1141} SQLite wil
77c0: 6c 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  l guarantee that
77d0: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 73   the zFilename s
77e0: 74 72 69 6e 67 20 70 61 73 73 65 64 20 74 6f 0a  tring passed to.
77f0: 2a 2a 20 78 4f 70 65 6e 28 29 20 69 73 20 61 20  ** xOpen() is a 
7800: 66 75 6c 6c 20 70 61 74 68 6e 61 6d 65 20 61 73  full pathname as
7810: 20 67 65 6e 65 72 61 74 65 64 20 62 79 20 78 46   generated by xF
7820: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 61 6e  ullPathname() an
7830: 64 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 74  d.** that the st
7840: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
7850: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
7860: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
7870: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 7b 45  is.** called. {E
7880: 4e 44 7d 20 20 53 6f 20 74 68 65 20 5b 73 71 6c  ND}  So the [sql
7890: 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73  ite3_file] can s
78a0: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
78b0: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
78c0: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
78d0: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
78e0: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
78f0: 72 65 61 73 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46  reason..**.** {F
7900: 31 31 31 34 32 7d 20 54 68 65 20 66 6c 61 67 73  11142} The flags
7910: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
7920: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  en() includes al
7930: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a  l bits set in.**
7940: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
7950: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
7960: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20  open_v2()].  Or 
7970: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  if [sqlite3_open
7980: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
7990: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20  e3_open16()] is 
79a0: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73  used, then flags
79b0: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61   includes at lea
79c0: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  st.** [SQLITE_OP
79d0: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
79e0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
79f0: 41 54 45 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49  ATE]. {END}.** I
7a00: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
7a10: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
7a20: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
7a30: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
7a40: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
7a50: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20  PEN_READONLY].  
7a60: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70  Other bits in *p
7a70: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20  OutFlags may be 
7a80: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31  set..**.** {F111
7a90: 34 33 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  43} SQLite will 
7aa0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
7ab0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
7ac0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
7ad0: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
7ae0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
7af0: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
7b00: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
7b10: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
7b20: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
7b30: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
7b40: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
7b50: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
7b60: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
7b70: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
7b80: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
7b90: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
7ba0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
7bb0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
7bc0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
7bd0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
7be0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
7bf0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
7c00: 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a  * </ul> {END}.**
7c10: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
7c20: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
7c30: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
7c40: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
7c50: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
7c60: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
7c70: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
7c80: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
7c90: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
7ca0: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
7cb0: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
7cc0: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
7cd0: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
7ce0: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
7cf0: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
7d00: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
7d10: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
7d20: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
7d30: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
7d40: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
7d50: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
7d60: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
7d70: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
7d80: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
7d90: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
7da0: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
7db0: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
7dc0: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
7dd0: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
7de0: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
7df0: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
7e00: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
7e10: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
7e20: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
7e30: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
7e40: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
7e50: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
7e60: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
7e70: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
7e80: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
7e90: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
7ea0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
7eb0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
7ec0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31  </ul>.**.** {F11
7ed0: 31 34 35 7d 20 54 68 65 20 5b 53 51 4c 49 54 45  145} The [SQLITE
7ee0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
7ef0: 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20  OSE] flag means 
7f00: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
7f10: 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68  be.** deleted wh
7f20: 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e  en it is closed.
7f30: 20 20 7b 46 31 31 31 34 36 7d 20 54 68 65 20 5b    {F11146} The [
7f40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
7f50: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69  TEONCLOSE].** wi
7f60: 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45  ll be set for TE
7f70: 4d 50 20 20 64 61 74 61 62 61 73 65 73 2c 20 6a  MP  databases, j
7f80: 6f 75 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20  ournals and for 
7f90: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a  subjournals..**.
7fa0: 2a 2a 20 7b 46 31 31 31 34 37 7d 20 54 68 65 20  ** {F11147} The 
7fb0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
7fc0: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 6d 65 61  LUSIVE] flag mea
7fd0: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
7fe0: 6c 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20  ld be opened.** 
7ff0: 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63  for exclusive ac
8000: 63 65 73 73 2e 20 20 54 68 69 73 20 66 6c 61 67  cess.  This flag
8010: 20 69 73 20 73 65 74 20 66 6f 72 20 61 6c 6c 20   is set for all 
8020: 66 69 6c 65 73 20 65 78 63 65 70 74 0a 2a 2a 20  files except.** 
8030: 66 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74  for the main dat
8040: 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  abase file..**.*
8050: 2a 20 7b 46 31 31 31 34 38 7d 20 41 74 20 6c 65  * {F11148} At le
8060: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
8070: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
8080: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
8090: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
80a0: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
80b0: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
80c0: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
80d0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
80e0: 20 78 4f 70 65 6e 2e 20 7b 45 4e 44 7d 20 20 54   xOpen. {END}  T
80f0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
8100: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
8110: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
8120: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
8130: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
8140: 69 74 20 69 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  it in..**.** {F1
8150: 31 31 34 39 7d 20 54 68 65 20 66 6c 61 67 73 20  1149} The flags 
8160: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63  argument to xAcc
8170: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51  ess() may be [SQ
8180: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
8190: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66  TS].** to test f
81a0: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65  or the existence
81b0: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b   of a file, or [
81c0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
81d0: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74  ADWRITE] to.** t
81e0: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
81f0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61  le is readable a
8200: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20  nd writable, or 
8210: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
8220: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  EAD].** to test 
8230: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
8240: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
8250: 62 6c 65 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20  ble. {END}  The 
8260: 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a  file can be a.**
8270: 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
8280: 2a 20 7b 46 31 31 31 35 30 7d 20 53 51 4c 69 74  * {F11150} SQLit
8290: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
82a0: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
82b0: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
82c0: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
82d0: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
82e0: 6c 50 61 74 68 6e 61 6d 65 2e 20 7b 46 31 31 31  lPathname. {F111
82f0: 35 31 7d 20 54 68 65 20 65 78 61 63 74 20 73 69  51} The exact si
8300: 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74  ze of the output
8310: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c   buffer.** is al
8320: 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70  so passed as a p
8330: 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68  arameter to both
8340: 20 20 6d 65 74 68 6f 64 73 2e 20 7b 45 4e 44 7d    methods. {END}
8350: 20 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20    If the output 
8360: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74  buffer.** is not
8370: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b   large enough, [
8380: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
8390: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
83a0: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20  ned. Since this 
83b0: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73  is.** handled as
83c0: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62   a fatal error b
83d0: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d  y SQLite, vfs im
83e0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
83f0: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a  ould endeavor.**
8400: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73   to prevent this
8410: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61   by setting mxPa
8420: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
8430: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
8440: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
8450: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
8460: 53 6c 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75  Sleep(), and xCu
8470: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65  rrentTime() inte
8480: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
8490: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
84a0: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
84b0: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
84c0: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
84d0: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
84e0: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
84f0: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
8500: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
8510: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
8520: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
8530: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
8540: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
8550: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
8560: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
8570: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
8580: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
8590: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
85a0: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53  ained..** The xS
85b0: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61  leep() method ca
85c0: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67  uses the calling
85d0: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70   thread to sleep
85e0: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74   for at.** least
85f0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   the number of m
8600: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65  icroseconds give
8610: 6e 2e 20 20 54 68 65 20 78 43 75 72 72 65 6e 74  n.  The xCurrent
8620: 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  Time().** method
8630: 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61   returns a Julia
8640: 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72  n Day Number for
8650: 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
8660: 65 20 61 6e 64 20 74 69 6d 65 2e 0a 2a 2f 0a 74  e and time..*/.t
8670: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
8680: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
8690: 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71  3_vfs;.struct sq
86a0: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
86b0: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
86c0: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
86d0: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
86e0: 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  er */.  int szOs
86f0: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
8700: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
8710: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
8720: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
8730: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
8740: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
8750: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
8760: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
8770: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
8780: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
8790: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
87a0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
87b0: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
87c0: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
87d0: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
87e0: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
87f0: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
8800: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
8810: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
8820: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
8830: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
8840: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
8850: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
8860: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
8870: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
8880: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
8890: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
88a0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
88b0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
88c0: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
88d0: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
88e0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
88f0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
8900: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
8910: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
8920: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
8930: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
8940: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
8950: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
8960: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
8970: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
8980: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
8990: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
89a0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
89b0: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
89c0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
89d0: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
89e0: 69 64 20 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  id *(*xDlSym)(sq
89f0: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
8a00: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
8a10: 79 6d 62 6f 6c 29 3b 0a 20 20 76 6f 69 64 20 28  ymbol);.  void (
8a20: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
8a30: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
8a40: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
8a50: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
8a60: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
8a70: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
8a80: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
8a90: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
8aa0: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
8ab0: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
8ac0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
8ad0: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
8ae0: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
8af0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
8b00: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
8b10: 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  /* New fields ma
8b20: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
8b30: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73   figure versions
8b40: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
8b50: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
8b60: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
8b70: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
8b80: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
8b90: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
8ba0: 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46  r the xAccess VF
8bb0: 53 20 6d 65 74 68 6f 64 20 7b 46 31 31 31 39 30  S method {F11190
8bc0: 7d 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 31 39 31 7d  }.**.** {F11191}
8bd0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
8be0: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
8bf0: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
8c00: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
8c10: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
8c20: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
8c30: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
8c40: 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 64 65 74   {END}  They det
8c50: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
8c60: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
8c70: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
8c80: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
8c90: 20 66 6f 72 2e 0a 2a 2a 20 7b 46 31 31 31 39 32   for..** {F11192
8ca0: 7d 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  } With SQLITE_AC
8cb0: 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65  CESS_EXISTS, the
8cc0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
8cd0: 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73  ** simply checks
8ce0: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
8cf0: 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 7b 46 31  e exists..** {F1
8d00: 31 31 39 33 7d 20 57 69 74 68 20 53 51 4c 49 54  1193} With SQLIT
8d10: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
8d20: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
8d30: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
8d40: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
8d50: 65 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62  e is both readab
8d60: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e  le and writable.
8d70: 0a 2a 2a 20 7b 46 31 31 31 39 34 7d 20 57 69 74  .** {F11194} Wit
8d80: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
8d90: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
8da0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
8db0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
8dc0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
8dd0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
8de0: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
8df0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
8e00: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
8e10: 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20  WRITE 1.#define 
8e20: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
8e30: 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a  AD      2../*.**
8e40: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
8e50: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
8e60: 20 4c 69 62 72 61 72 79 20 7b 46 31 30 31 33 30   Library {F10130
8e70: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
8e80: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
8e90: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
8ea0: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
8eb0: 74 65 20 6c 69 62 72 61 72 79 20 70 72 69 6f 72  te library prior
8ec0: 20 74 6f 20 75 73 65 2e 20 20 54 68 65 20 73 71   to use.  The sq
8ed0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
8ee0: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
8ef0: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
8f00: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
8f10: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
8f20: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
8f30: 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  )..**.** A call 
8f40: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
8f50: 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65  alize() is an "e
8f60: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
8f70: 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66  f it is.** the f
8f80: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
8f90: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
8fa0: 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67  s invoked during
8fb0: 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
8fc0: 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c  .** the process,
8fd0: 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65   or if it is the
8fe0: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
8ff0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9000: 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66   is invoked.** f
9010: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20  ollowing a call 
9020: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
9030: 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79 20 61 6e 20  own().  Only an 
9040: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a  effective call.*
9050: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69  * of sqlite3_ini
9060: 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61  tialize() does a
9070: 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ny initializatio
9080: 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  n.  All other ca
9090: 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c  lls.** are harml
90a0: 65 73 73 20 6e 6f 2d 6f 70 73 2e 20 20 49 6e 20  ess no-ops.  In 
90b0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20  other words,.** 
90c0: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  the sqlite3_init
90d0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
90e0: 20 6d 61 79 20 62 65 20 63 61 6c 6c 65 64 20 6d   may be called m
90f0: 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 0a 2a 2a  ultiple times.**
9100: 20 77 69 74 68 6f 75 74 20 63 6f 6e 73 65 71 75   without consequ
9110: 65 6e 63 65 2e 20 20 53 65 63 6f 6e 64 20 61 6e  ence.  Second an
9120: 64 20 73 75 62 73 65 71 75 65 6e 74 20 65 76 61  d subsequent eva
9130: 6c 75 61 74 69 6f 6e 73 20 6f 66 0a 2a 2a 20 73  luations of.** s
9140: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9150: 65 28 29 20 61 72 65 20 6e 6f 2d 6f 70 73 2e 20  e() are no-ops. 
9160: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
9170: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
9180: 65 0a 2a 2a 20 6f 6e 6c 79 20 77 6f 72 6b 73 20  e.** only works 
9190: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 69  the first time i
91a0: 74 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20  t is called for 
91b0: 61 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 74 68  a process, or th
91c0: 65 20 66 69 72 73 74 0a 2a 2a 20 74 69 6d 65 20  e first.** time 
91d0: 69 74 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74  it is called aft
91e0: 65 72 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  er sqlite3_shutd
91f0: 6f 77 6e 28 29 2e 20 20 49 6e 20 61 6c 6c 20 6f  own().  In all o
9200: 74 68 65 72 20 63 61 73 65 73 2c 0a 2a 2a 20 73  ther cases,.** s
9210: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9220: 65 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  e() returns SQLI
9230: 54 45 5f 4f 4b 20 77 69 74 68 6f 75 74 20 64 6f  TE_OK without do
9240: 69 6e 67 20 61 6e 79 20 72 65 61 6c 20 77 6f 72  ing any real wor
9250: 6b 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  k..**.** Among o
9260: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 73 71 6c  ther things, sql
9270: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9280: 29 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  ) shall invoke.*
9290: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
92a0: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
92b0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
92c0: 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c 20 69 6e 76  n().** shall inv
92d0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
92e0: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nd()..**.** The 
92f0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9300: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
9310: 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20 6f  urns SQLITE_OK o
9320: 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 49 66  n success..** If
9330: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
9340: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  , sqlite3_initia
9350: 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65  lize() is unable
9360: 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a   to initialize.*
9370: 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70  * the library (p
9380: 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61  erhaps it is una
9390: 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
93a0: 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63  a needed resourc
93b0: 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d  e such.** as a m
93c0: 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73  utex) it returns
93d0: 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
93e0: 20 6f 74 68 65 72 20 74 68 61 6e 20 53 51 4c 49   other than SQLI
93f0: 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  TE_OK..**.** The
9400: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9410: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
9420: 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
9430: 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
9440: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
9450: 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
9460: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
9470: 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
9480: 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
9490: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
94a0: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
94b0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
94c0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
94d0: 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
94e0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
94f0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
9500: 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
9510: 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
9520: 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
9530: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
9540: 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
9550: 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
9560: 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
9570: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c   However, if SQL
9580: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
9590: 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
95a0: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 0a 2a 2a  OMIT_AUTOINIT.**
95b0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
95c0: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
95d0: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
95e0: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
95f0: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
9600: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
9610: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
9620: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
9630: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
9640: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
9650: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
9660: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
9670: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
9680: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
9690: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
96a0: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
96b0: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
96c0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
96d0: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
96e0: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
96f0: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
9700: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
9710: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
9720: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
9730: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
9740: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
9750: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
9760: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
9770: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
9780: 74 68 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  th SQLITE_OMIT_A
9790: 55 54 4f 49 4e 49 54 20 6d 69 67 68 74 20 62 65  UTOINIT might be
97a0: 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61  come the.** defa
97b0: 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20  ult behavior in 
97c0: 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
97d0: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
97e0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
97f0: 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69  _os_init() routi
9800: 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e  ne does operatin
9810: 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
9820: 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74  c.** initializat
9830: 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ion of the SQLit
9840: 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  e library.  The 
9850: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
9860: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f  .** routine undo
9870: 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66  es the effect of
9880: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
9890: 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73  ().  Typical tas
98a0: 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ks.** performed 
98b0: 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  by these routine
98c0: 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61  s include alloca
98d0: 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tion or dealloca
98e0: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69  tion.** of stati
98f0: 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69  c resources, ini
9900: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67  tialization of g
9910: 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c  lobal variables,
9920: 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61  .** setting up a
9930: 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
9940: 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f  3_vfs] module, o
9950: 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20  r setting up.** 
9960: 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  a default config
9970: 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73  uration using [s
9980: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
9990: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
99a0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
99b0: 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68  ever invoke eith
99c0: 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  er sqlite3_os_in
99d0: 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  it().** or sqlit
99e0: 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65  e3_os_end() dire
99f0: 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69  ctly.  The appli
9a00: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e  cation should on
9a10: 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ly invoke.** sql
9a20: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9a30: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68  ) and sqlite3_sh
9a40: 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73  utdown().  The s
9a50: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
9a60: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
9a70: 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69   called automati
9a80: 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
9a90: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
9aa0: 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  d.** sqlite3_os_
9ab0: 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20  end() is called 
9ac0: 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  by sqlite3_shutd
9ad0: 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69  own().  Appropri
9ae0: 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ate.** implement
9af0: 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74  ations for sqlit
9b00: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
9b10: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
9b20: 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69  ).** are built i
9b30: 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20  nto SQLite when 
9b40: 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66  it is compiled f
9b50: 6f 72 20 75 6e 69 78 2c 20 77 69 6e 64 6f 77 73  or unix, windows
9b60: 2c 20 6f 72 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68  , or os/2..** Wh
9b70: 65 6e 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68  en built for oth
9b80: 65 72 20 70 6c 61 74 66 6f 72 6d 73 20 28 75 73  er platforms (us
9b90: 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  ing the SQLITE_O
9ba0: 53 5f 4f 54 48 45 52 3d 31 20 63 6f 6d 70 69 6c  S_OTHER=1 compil
9bb0: 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
9bc0: 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
9bd0: 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
9be0: 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
9bf0: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
9c00: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
9c10: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
9c20: 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
9c30: 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
9c40: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
9c50: 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
9c60: 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
9c70: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
9c80: 73 74 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  st return SQLITE
9c90: 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 20 61  _OK on success a
9ca0: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
9cb0: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
9cc0: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
9cd0: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
9ce0: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
9cf0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
9d00: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
9d10: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
9d20: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
9d30: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
9d40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
9d50: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
9d60: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 46  QLite Library {F
9d70: 31 30 31 34 35 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  10145}.**.** The
9d80: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
9d90: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
9da0: 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62  sed to make glob
9db0: 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  al configuration
9dc0: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53  .** changes to S
9dd0: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
9de0: 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f  o tune SQLite to
9df0: 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
9e00: 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  eds of.** the ap
9e10: 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20  plication.  The 
9e20: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
9e30: 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65  ation is recomme
9e40: 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a  nded for most.**
9e50: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e   applications an
9e60: 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  d so this routin
9e70: 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74  e is usually not
9e80: 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20   necessary.  It 
9e90: 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74  is.** provided t
9ea0: 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61  o support rare a
9eb0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68  pplications with
9ec0: 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a   unusual needs..
9ed0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
9ee0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
9ef0: 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65  face is not thre
9f00: 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70  adsafe.  The app
9f10: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  lication.** must
9f20: 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20   insure that no 
9f30: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
9f40: 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f  erfaces are invo
9f50: 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20  ked by other.** 
9f60: 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71  threads while sq
9f70: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
9f80: 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74  s running.  Furt
9f90: 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33  hermore, sqlite3
9fa0: 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79  _config().** may
9fb0: 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64   only be invoked
9fc0: 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72   prior to librar
9fd0: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
9fe0: 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
9ff0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
a000: 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f   or after shutdo
a010: 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  wn by [sqlite3_s
a020: 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 4e  hutdown()]..** N
a030: 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
a040: 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  at sqlite3_confi
a050: 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  g() can be calle
a060: 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
a070: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
a080: 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61  on of an applica
a090: 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71  tion-defined [sq
a0a0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d  lite3_os_init()]
a0b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
a0c0: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  t argument to sq
a0d0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
a0e0: 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  s an integer.** 
a0f0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
a100: 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f  INGLETHREAD | co
a110: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
a120: 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
a130: 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
a140: 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
a150: 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
a160: 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
a170: 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
a180: 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
a190: 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
a1a0: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c  G_SINGLETHREAD |
a1b0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
a1c0: 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ption].** in the
a1d0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
a1e0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63 6f  .**.** When a co
a1f0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
a200: 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74  on is set, sqlit
a210: 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  e3_config() retu
a220: 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a  rns SQLITE_OK..*
a230: 2a 20 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20  * If the option 
a240: 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51  is unknown or SQ
a250: 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
a260: 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e  o set the option
a270: 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f  .** then this ro
a280: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
a290: 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
a2a0: 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  code]..*/.int sq
a2b0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
a2c0: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
a2d0: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
a2e0: 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
a2f0: 6e 65 73 20 7b 46 31 30 31 35 35 7d 0a 2a 2a 0a  nes {F10155}.**.
a300: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
a310: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65  f this object de
a320: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
a330: 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69  ace between SQLi
a340: 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65  te.** and low-le
a350: 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
a360: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a  ation routines..
a370: 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  **.** This objec
a380: 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c  t is used in onl
a390: 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74  y one place in t
a3a0: 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  he SQLite interf
a3b0: 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  ace..** A pointe
a3c0: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
a3d0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
a3e0: 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  is the argument 
a3f0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
a400: 6f 6e 66 69 67 5d 20 77 68 65 6e 20 74 68 65 20  onfig] when the 
a410: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
a420: 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
a430: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
a440: 5d 2e 20 20 42 79 20 63 72 65 61 74 69 6e 67 20  ].  By creating 
a450: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
a460: 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
a470: 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
a480: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
a490: 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
a4a0: 61 74 69 6f 6e 2c 20 61 6e 0a 2a 2a 20 61 70 70  ation, an.** app
a4b0: 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
a4c0: 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
a4d0: 69 76 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ive memory alloc
a4e0: 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 0a  ation subsystem.
a4f0: 2a 2a 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  ** for SQLite to
a500: 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
a510: 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
a520: 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
a530: 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
a540: 20 63 6f 6d 65 73 20 77 69 74 68 20 61 20 62 75   comes with a bu
a550: 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
a560: 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 69 73 0a  locator that is.
a570: 2a 2a 20 70 65 72 66 65 63 74 6c 79 20 61 64 65  ** perfectly ade
a580: 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76  quate for the ov
a590: 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72  erwhelming major
a5a0: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
a5b0: 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ons.** and that 
a5c0: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f  this object is o
a5d0: 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20  nly useful to a 
a5e0: 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66  tiny minority of
a5f0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
a600: 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65   with specialize
a610: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
a620: 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73  ion requirements
a630: 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  .  This object i
a640: 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64  s.** also used d
a650: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66  uring testing of
a660: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
a670: 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61   to specify an a
a680: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
a690: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74  mory allocator t
a6a0: 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65  hat simulates me
a6b0: 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f  mory out-of-memo
a6c0: 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e  ry conditions in
a6d0: 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72  .** order to ver
a6e0: 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20  ify that SQLite 
a6f0: 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75  recovers gracefu
a700: 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a  lly from such.**
a710: 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a   conditions..**.
a720: 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20  ** The xMalloc, 
a730: 78 46 72 65 65 2c 20 61 6e 64 20 78 52 65 61 6c  xFree, and xReal
a740: 6c 6f 63 20 6d 65 74 68 6f 64 73 20 73 68 6f 75  loc methods shou
a750: 6c 64 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65  ld work like the
a760: 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 66 72  .** malloc(), fr
a770: 65 65 28 29 2c 20 61 6e 64 20 72 65 61 6c 6c 6f  ee(), and reallo
a780: 63 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72  c() functions fr
a790: 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
a7a0: 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 78  library..**.** x
a7b0: 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
a7c0: 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
a7d0: 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
a7e0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
a7f0: 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
a800: 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
a810: 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
a820: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
a830: 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
a840: 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
a850: 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
a860: 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
a870: 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
a880: 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
a890: 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
a8a0: 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
a8b0: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
a8c0: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
a8d0: 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
a8e0: 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
a8f0: 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
a900: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
a910: 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
a920: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
a930: 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
a940: 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
a950: 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
a960: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
a970: 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
a980: 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
a990: 65 72 20 6f 66 20 32 2e 0a 2a 2a 0a 2a 2a 20 54  er of 2..**.** T
a9a0: 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
a9b0: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
a9c0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
a9d0: 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .  (For example,
a9e0: 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c  .** it might all
a9f0: 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72  ocate any requir
aa00: 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69  e mutexes or ini
aa10: 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c  tialize internal
aa20: 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75   data.** structu
aa30: 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64  res.  The xShutd
aa40: 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  own method is in
aa50: 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c  voked (indirectl
aa60: 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  y) by.** [sqlite
aa70: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e  3_shutdown()] an
aa80: 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63  d should dealloc
aa90: 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65  ate any resource
aaa0: 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79  s acquired.** by
aab0: 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70   xInit.  The pAp
aac0: 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73  pData pointer is
aad0: 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c   used as the onl
aae0: 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  y parameter to.*
aaf0: 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75  * xInit and xShu
ab00: 74 64 6f 77 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  tdown..*/.typede
ab10: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
ab20: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c  _mem_methods sql
ab30: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
ab40: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
ab50: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  _mem_methods {. 
ab60: 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63   void *(*xMalloc
ab70: 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
ab80: 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  /* Memory alloca
ab90: 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  tion function */
aba0: 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29  .  void (*xFree)
abb0: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
abc0: 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f    /* Free a prio
abd0: 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  r allocation */.
abe0: 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c    void *(*xReall
abf0: 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20  oc)(void*,int); 
ac00: 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c   /* Resize an al
ac10: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
ac20: 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a  t (*xSize)(void*
ac30: 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
ac40: 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20  Return the size 
ac50: 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  of an allocation
ac60: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75   */.  int (*xRou
ac70: 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20  ndup)(int);     
ac80: 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70       /* Round up
ac90: 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f   request size to
aca0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
acb0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69   */.  int (*xIni
acc0: 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  t)(void*);      
acd0: 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69       /* Initiali
ace0: 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
acf0: 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
ad00: 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76  d (*xShutdown)(v
ad10: 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44  oid*);      /* D
ad20: 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20  einitialize the 
ad30: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
ad40: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
ad50: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20  Data;           
ad60: 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74       /* Argument
ad70: 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20   to xInit() and 
ad80: 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d  xShutdown() */.}
ad90: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
ada0: 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
adb0: 20 4f 70 74 69 6f 6e 73 20 7b 46 31 30 31 36 30   Options {F10160
adc0: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
add0: 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
ade0: 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
adf0: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
ae00: 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
ae10: 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
ae20: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
ae30: 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
ae40: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
ae50: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c  terface..**.** <
ae60: 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
ae70: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
ae80: 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
ae90: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
aea0: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
aeb0: 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f   option.  This o
aec0: 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a  ption disables.*
aed0: 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61  * all mutexing a
aee0: 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69  nd puts SQLite i
aef0: 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65  nto a mode where
af00: 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20   it can only be 
af10: 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e  used.** by a sin
af20: 67 6c 65 20 74 68 72 65 61 64 2e 3c 2f 64 64 3e  gle thread.</dd>
af30: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
af40: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
af50: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
af60: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
af70: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
af80: 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70  option.  This op
af90: 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a  tion disables.**
afa0: 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
afb0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
afc0: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
afd0: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
afe0: 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
aff0: 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
b000: 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
b010: 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
b020: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
b030: 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
b040: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
b050: 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
b060: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
b070: 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
b080: 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
b090: 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
b0a0: 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
b0b0: 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2e 3c 2f  * environment.</
b0c0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
b0d0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
b0e0: 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
b0f0: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
b100: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
b110: 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20  s option.  This 
b120: 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
b130: 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
b140: 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
b150: 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
b160: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
b170: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
b180: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
b190: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
b1a0: 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
b1b0: 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
b1c0: 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
b1d0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
b1e0: 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  * SQLITE_THREADS
b1f0: 41 46 45 3d 31 29 20 74 68 65 20 53 51 4c 69 74  AFE=1) the SQLit
b200: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
b210: 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
b220: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
b230: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
b240: 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
b250: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
b260: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
b270: 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
b280: 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
b290: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
b2a0: 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
b2b0: 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
b2c0: 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
b2d0: 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
b2e0: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
b2f0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
b300: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
b310: 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
b320: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
b330: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
b340: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
b350: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
b360: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
b370: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
b380: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
b390: 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
b3a0: 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
b3b0: 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
b3c0: 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
b3d0: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
b3e0: 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
b3f0: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
b400: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
b410: 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
b420: 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a  to SQLite.</dd>.
b430: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
b440: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
b450: 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  C</dt>.** <dd>Th
b460: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
b470: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
b480: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
b490: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
b4a0: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
b4b0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
b4c0: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
b4d0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
b4e0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
b4f0: 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
b500: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
b510: 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
b520: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
b530: 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20  utines..** This 
b540: 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
b550: 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
b560: 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
b570: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
b580: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
b590: 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
b5a0: 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
b5b0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
b5c0: 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
b5d0: 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
b5e0: 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a  r example.</dd>.
b5f0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
b600: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
b610: 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  S</dt>.** <dd>Th
b620: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
b630: 73 69 6e 67 6c 65 20 62 6f 6f 6c 65 61 6e 20 61  single boolean a
b640: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 65 6e  rgument which en
b650: 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
b660: 73 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 65 63 74  s.** the collect
b670: 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c  ion of memory al
b680: 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
b690: 69 63 73 2e 20 20 57 68 65 6e 20 64 69 73 61 62  ics.  When disab
b6a0: 6c 65 64 2c 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c  led, the.** foll
b6b0: 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
b6c0: 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e  erfaces become n
b6d0: 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a  on-operational:.
b6e0: 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  **   <ul>.**   <
b6f0: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
b700: 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20  ory_used()].**  
b710: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
b720: 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
b730: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
b740: 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
b750: 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c  limit()].**   <l
b760: 69 3e 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  i> sqlite3_memor
b770: 79 5f 73 74 61 74 75 73 28 29 0a 2a 2a 20 20 20  y_status().**   
b780: 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  </ul>.** </dd>.*
b790: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
b7a0: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f  CONFIG_SCRATCH</
b7b0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
b7c0: 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
b7d0: 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
b7e0: 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
b7f0: 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a  ite can use for.
b800: 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
b810: 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68  y.  There are th
b820: 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20  ree arguments:  
b830: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
b840: 20 6d 65 6d 6f 72 79 2c 20 74 68 65 0a 2a 2a 20   memory, the.** 
b850: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72  size of each scr
b860: 61 74 63 68 20 62 75 66 66 65 72 20 28 73 7a 29  atch buffer (sz)
b870: 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
b880: 20 6f 66 20 62 75 66 66 65 72 73 20 28 4e 29 2e   of buffers (N).
b890: 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75    The sz.** argu
b8a0: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d  ment must be a m
b8b0: 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 54  ultiple of 16. T
b8c0: 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
b8d0: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e  ment should poin
b8e0: 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69  t to an allocati
b8f0: 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 28  on of at least (
b900: 73 7a 2b 34 29 2a 4e 20 62 79 74 65 73 20 6f 66  sz+4)*N bytes of
b910: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69   memory..** SQLi
b920: 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d  te will use no m
b930: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72  ore than one scr
b940: 61 74 63 68 20 62 75 66 66 65 72 20 61 74 20 6f  atch buffer at o
b950: 6e 63 65 20 70 65 72 20 74 68 72 65 61 64 2c 20  nce per thread, 
b960: 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62  so.** N should b
b970: 65 20 73 65 74 20 74 6f 20 74 68 65 20 65 78 70  e set to the exp
b980: 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75  ected maximum nu
b990: 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e  mber of threads.
b9a0: 20 20 54 68 65 20 73 7a 0a 2a 2a 20 70 61 72 61    The sz.** para
b9b0: 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20  meter should be 
b9c0: 36 20 74 69 6d 65 73 20 74 68 65 20 73 69 7a 65  6 times the size
b9d0: 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
b9e0: 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
b9f0: 7a 65 2e 0a 2a 2a 20 53 63 72 61 74 63 68 20 62  ze..** Scratch b
ba00: 75 66 66 65 72 73 20 61 72 65 20 75 73 65 64 20  uffers are used 
ba10: 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 62  as part of the b
ba20: 74 72 65 65 20 62 61 6c 61 6e 63 65 20 6f 70 65  tree balance ope
ba30: 72 61 74 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20 54  ration.  If.** T
ba40: 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65  he btree balance
ba50: 72 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e  r needs addition
ba60: 61 6c 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64  al memory beyond
ba70: 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
ba80: 64 20 62 79 0a 2a 2a 20 73 63 72 61 74 63 68 20  d by.** scratch 
ba90: 62 75 66 66 65 72 73 20 6f 72 20 69 66 20 6e 6f  buffers or if no
baa0: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
bab0: 73 70 61 63 65 20 69 73 20 73 70 65 63 69 66 69  space is specifi
bac0: 65 64 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a  ed, then SQLite.
bad0: 2a 2a 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  ** goes to [sqli
bae0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74 6f  te3_malloc()] to
baf0: 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
bb00: 72 79 20 69 74 20 6e 65 65 64 73 2e 3c 2f 64 64  ry it needs.</dd
bb10: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
bb20: 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
bb30: 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
bb40: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
bb50: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
bb60: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
bb70: 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
bb80: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61   for.** the data
bb90: 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 2e  base page cache.
bba0: 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65    There are thre
bbb0: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 70  e arguments: A p
bbc0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
bbd0: 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a   memory, the siz
bbe0: 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62  e of each page b
bbf0: 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
bc00: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
bc10: 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  ges (N)..** The 
bc20: 73 7a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  sz argument must
bc30: 20 62 65 20 61 20 70 6f 77 65 72 20 6f 66 20 74   be a power of t
bc40: 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
bc50: 6e 64 20 33 32 37 36 38 2e 20 20 54 68 65 20 66  nd 32768.  The f
bc60: 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  irst.** argument
bc70: 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f   should point to
bc80: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f   an allocation o
bc90: 66 20 61 74 20 6c 65 61 73 74 20 28 73 7a 2b 34  f at least (sz+4
bca0: 29 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  )*N bytes of mem
bcb0: 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ory..** SQLite w
bcc0: 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f  ill use the memo
bcd0: 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  ry provided by t
bce0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
bcf0: 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73  t to satisfy its
bd00: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  .** memory needs
bd10: 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e   for the first N
bd20: 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61   pages that it a
bd30: 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 49  dds to cache.  I
bd40: 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
bd50: 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
bd60: 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
bd70: 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
bd80: 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69  ded by this opti
bd90: 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  on, then.** SQLi
bda0: 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  te goes to [sqli
bdb0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f  te3_malloc()] fo
bdc0: 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c  r the additional
bdd0: 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 3c   storage space.<
bde0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
bdf0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
be00: 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
be10: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
be20: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
be30: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
be40: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
be50: 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ** for all of it
be60: 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
be70: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
be80: 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  s beyond those p
be90: 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62  rovided.** for b
bea0: 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
beb0: 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53  _SCRATCH] and [S
bec0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
bed0: 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72  ECACHE]..** Ther
bee0: 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
bef0: 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e 74 65 72  ments: A pointer
bf00: 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20   to the memory, 
bf10: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
bf20: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
bf30: 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
bf40: 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
bf50: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 20 20 57  ocation size.  W
bf60: 68 65 6e 0a 2a 2a 20 74 68 69 73 20 63 6f 6e 66  hen.** this conf
bf70: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
bf80: 20 69 73 20 75 73 65 64 2c 20 53 51 4c 69 74 65   is used, SQLite
bf90: 20 6e 65 76 65 72 20 63 61 6c 6c 73 20 74 68 65   never calls the
bfa0: 20 73 79 73 74 65 6d 0a 2a 2a 20 6d 61 6c 6c 6f   system.** mallo
bfb0: 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
bfc0: 6f 6e 20 62 75 74 20 69 6e 73 74 65 61 64 20 75  on but instead u
bfd0: 73 65 73 20 74 68 65 20 73 75 70 70 6c 69 65 64  ses the supplied
bfe0: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a   memory buffer.*
bff0: 2a 20 74 6f 20 73 61 74 69 73 66 79 20 61 6c 6c  * to satisfy all
c000: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
c010: 28 29 5d 20 72 65 71 75 65 73 74 73 2e 3c 2f 64  ()] requests.</d
c020: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
c030: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
c040: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
c050: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
c060: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
c070: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
c080: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
c090: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
c0a0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
c0b0: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
c0c0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
c0d0: 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
c0e0: 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
c0f0: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
c100: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
c110: 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ace.** the mutex
c120: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
c130: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64  into SQLite.</dd
c140: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
c150: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
c160: 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
c170: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
c180: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
c190: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
c1a0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
c1b0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
c1c0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
c1d0: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
c1e0: 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
c1f0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
c200: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
c210: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
c220: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
c230: 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
c240: 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  nes..** This opt
c250: 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
c260: 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
c270: 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
c280: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
c290: 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
c2a0: 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
c2b0: 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
c2c0: 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
c2d0: 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
c2e0: 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
c2f0: 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  le.</dd>.**.** <
c300: 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
c310: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
c320: 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
c330: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
c340: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
c350: 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
c360: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
c370: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
c380: 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
c390: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
c3a0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
c3b0: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
c3c0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
c3d0: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
c3e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
c3f0: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
c400: 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
c410: 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
c420: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
c430: 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
c440: 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
c450: 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
c460: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c470: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
c480: 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
c490: 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
c4a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
c4b0: 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
c4c0: 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
c4d0: 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
c4e0: 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
c4f0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
c500: 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
c510: 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
c520: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
c530: 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
c540: 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
c550: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
c560: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
c570: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
c580: 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
c590: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
c5a0: 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ds* */../*.** CA
c5b0: 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
c5c0: 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
c5d0: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20  ed Result Codes 
c5e0: 7b 46 31 32 32 30 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12200}.**.** T
c5f0: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
c600: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
c610: 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  () routine enabl
c620: 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
c630: 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  he.** [extended 
c640: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
c650: 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e  ature of SQLite.
c660: 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65   The extended re
c670: 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
c680: 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
c690: 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
c6a0: 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
c6b0: 74 79 20 63 6f 6e 73 69 64 65 72 61 74 69 6f 6e  ty consideration
c6c0: 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  s..**.** INVARIA
c6d0: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  NTS:.**.** {F122
c6e0: 30 31 7d 20 45 61 63 68 20 6e 65 77 20 5b 64 61  01} Each new [da
c6f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
c700: 6e 5d 20 73 68 61 6c 6c 20 68 61 76 65 20 74 68  n] shall have th
c710: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65  e.**          [e
c720: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
c730: 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 64 69  odes] feature di
c740: 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
c750: 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 30 32  t..**.** {F12202
c760: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  } The [sqlite3_e
c770: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
c780: 6f 64 65 73 28 44 2c 46 29 5d 20 69 6e 74 65 72  odes(D,F)] inter
c790: 66 61 63 65 20 73 68 61 6c 6c 20 65 6e 61 62 6c  face shall enabl
c7a0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65  e.**          [e
c7b0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
c7c0: 6f 64 65 73 5d 20 66 6f 72 20 74 68 65 20 20 5b  odes] for the  [
c7d0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c7e0: 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20  ion] D.**       
c7f0: 20 20 20 69 66 20 74 68 65 20 46 20 70 61 72 61     if the F para
c800: 6d 65 74 65 72 20 69 73 20 74 72 75 65 2c 20 6f  meter is true, o
c810: 72 20 64 69 73 61 62 6c 65 20 74 68 65 6d 20 69  r disable them i
c820: 66 20 46 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2f  f F is false..*/
c830: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
c840: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
c850: 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
c860: 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
c870: 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
c880: 6e 73 65 72 74 20 52 6f 77 69 64 20 7b 46 31 32  nsert Rowid {F12
c890: 32 32 30 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20  220}.**.** Each 
c8a0: 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69  entry in an SQLi
c8b0: 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75  te table has a u
c8c0: 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
c8d0: 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
c8e0: 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 22 72  ey called the "r
c8f0: 6f 77 69 64 22 2e 20 54 68 65 20 72 6f 77 69 64  owid". The rowid
c900: 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c   is always avail
c910: 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e  able.** as an un
c920: 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20  declared column 
c930: 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44  named ROWID, OID
c940: 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20  , or _ROWID_ as 
c950: 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a  long as those.**
c960: 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61   names are not a
c970: 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c  lso used by expl
c980: 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
c990: 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74  columns. If.** t
c9a0: 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63  he table has a c
c9b0: 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 49 4e  olumn of type IN
c9c0: 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
c9d0: 59 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75  Y then that colu
c9e0: 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72  mn.** is another
c9f0: 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72   alias for the r
ca00: 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  owid..**.** This
ca10: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
ca20: 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
ca30: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a  e most recent.**
ca40: 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45   successful INSE
ca50: 52 54 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  RT into the data
ca60: 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64  base from the [d
ca70: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
ca80: 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
ca90: 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 49  rst argument.  I
caa0: 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20  f no successful 
cab0: 49 4e 53 45 52 54 73 0a 2a 2a 20 68 61 76 65 20  INSERTs.** have 
cac0: 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
cad0: 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63   that database c
cae0: 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20  onnection, zero 
caf0: 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
cb00: 2a 2a 20 49 66 20 61 6e 20 49 4e 53 45 52 54 20  ** If an INSERT 
cb10: 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
cb20: 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68  trigger, then th
cb30: 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 69  e rowid of the i
cb40: 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69  nserted.** row i
cb50: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
cb60: 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f  is routine as lo
cb70: 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
cb80: 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  r is running..**
cb90: 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72   But once the tr
cba0: 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73  igger terminates
cbb0: 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
cbc0: 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75  rned by this rou
cbd0: 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73 20  tine.** reverts 
cbe0: 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75  to the last valu
cbf0: 65 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72  e inserted befor
cc00: 65 20 74 68 65 20 74 72 69 67 67 65 72 20 66 69  e the trigger fi
cc10: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 49 4e  red..**.** An IN
cc20: 53 45 52 54 20 74 68 61 74 20 66 61 69 6c 73 20  SERT that fails 
cc30: 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61  due to a constra
cc40: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73  int violation is
cc50: 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73   not a.** succes
cc60: 73 66 75 6c 20 49 4e 53 45 52 54 20 61 6e 64 20  sful INSERT and 
cc70: 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
cc80: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
cc90: 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
cca0: 75 74 69 6e 65 2e 20 20 54 68 75 73 20 49 4e 53  utine.  Thus INS
ccb0: 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
ccc0: 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
ccd0: 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
cce0: 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
ccf0: 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
cd00: 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
cd10: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
cd20: 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
cd30: 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
cd40: 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57 68  rtion fails.  Wh
cd50: 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
cd60: 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
cd70: 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
cd80: 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
cd90: 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
cda0: 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
cdb0: 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
cdc0: 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
cdd0: 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
cde0: 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
cdf0: 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
ce00: 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
ce10: 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
ce20: 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
ce30: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
ce40: 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
ce50: 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f  ** For the purpo
ce60: 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
ce70: 69 6e 65 2c 20 61 6e 20 49 4e 53 45 52 54 20 69  ine, an INSERT i
ce80: 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a  s considered to.
ce90: 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c  ** be successful
cea0: 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73   even if it is s
ceb0: 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c  ubsequently roll
cec0: 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49  ed back..**.** I
ced0: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
cee0: 20 7b 46 31 32 32 32 31 7d 20 54 68 65 20 5b 73   {F12221} The [s
cef0: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
cf00: 72 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63  rt_rowid()] func
cf10: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
cf20: 20 72 6f 77 69 64 0a 2a 2a 20 20 20 20 20 20 20   rowid.**       
cf30: 20 20 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72     of the most r
cf40: 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c  ecent successful
cf50: 20 49 4e 53 45 52 54 20 70 65 72 66 6f 72 6d 65   INSERT performe
cf60: 64 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  d on the same.**
cf70: 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
cf80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
cf90: 61 6e 64 20 77 69 74 68 69 6e 20 74 68 65 20 73  and within the s
cfa0: 61 6d 65 20 6f 72 20 68 69 67 68 65 72 20 6c 65  ame or higher le
cfb0: 76 65 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  vel.**          
cfc0: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c  trigger context,
cfd0: 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72   or zero if ther
cfe0: 65 20 68 61 76 65 20 62 65 65 6e 20 6e 6f 20 71  e have been no q
cff0: 75 61 6c 69 66 79 69 6e 67 20 69 6e 73 65 72 74  ualifying insert
d000: 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 32 33  s..**.** {F12223
d010: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  } The [sqlite3_l
d020: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
d030: 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  ()] function ret
d040: 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
d050: 20 20 20 20 20 73 61 6d 65 20 76 61 6c 75 65 20       same value 
d060: 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d  when called from
d070: 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
d080: 72 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20  r context.**    
d090: 20 20 20 20 20 20 69 6d 6d 65 64 69 61 74 65 6c        immediatel
d0a0: 79 20 62 65 66 6f 72 65 20 61 6e 64 20 61 66 74  y before and aft
d0b0: 65 72 20 61 20 52 4f 4c 4c 42 41 43 4b 2e 0a 2a  er a ROLLBACK..*
d0c0: 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53  *.** LIMITATIONS
d0d0: 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 33 32 7d  :.**.** {U12232}
d0e0: 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
d0f0: 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61  hread performs a
d100: 20 6e 65 77 20 49 4e 53 45 52 54 20 6f 6e 20 74   new INSERT on t
d110: 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he same.**      
d120: 20 20 20 20 64 61 74 61 62 61 73 65 20 63 6f 6e      database con
d130: 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
d140: 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
d150: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
d160: 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63  **          func
d170: 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20  tion is running 
d180: 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73  and thus changes
d190: 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
d1a0: 20 72 6f 77 69 64 2c 0a 2a 2a 20 20 20 20 20 20   rowid,.**      
d1b0: 20 20 20 20 74 68 65 6e 20 74 68 65 20 76 61 6c      then the val
d1c0: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ue returned by [
d1d0: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
d1e0: 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a  ert_rowid()] is.
d1f0: 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e 70 72  **          unpr
d200: 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69  edictable and mi
d210: 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69  ght not equal ei
d220: 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20  ther the old or 
d230: 74 68 65 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20  the new.**      
d240: 20 20 20 20 6c 61 73 74 20 69 6e 73 65 72 74 20      last insert 
d250: 72 6f 77 69 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65  rowid..*/.sqlite
d260: 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
d270: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
d280: 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
d290: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
d2a0: 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
d2b0: 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20  f Rows Modified 
d2c0: 7b 46 31 32 32 34 30 7d 0a 2a 2a 0a 2a 2a 20 54  {F12240}.**.** T
d2d0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
d2e0: 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
d2f0: 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73  of database rows
d300: 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67   that were chang
d310: 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65  ed.** or inserte
d320: 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20  d or deleted by 
d330: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
d340: 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20  y completed SQL 
d350: 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20  statement.** on 
d360: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
d370: 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
d380: 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ied by the first
d390: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f   parameter..** O
d3a0: 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74  nly changes that
d3b0: 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70   are directly sp
d3c0: 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 49  ecified by the I
d3d0: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 0a 2a  NSERT, UPDATE,.*
d3e0: 2a 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  * or DELETE stat
d3f0: 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65  ement are counte
d400: 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68  d.  Auxiliary ch
d410: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a  anges caused by.
d420: 2a 2a 20 74 72 69 67 67 65 72 73 20 61 72 65 20  ** triggers are 
d430: 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 55 73 65  not counted. Use
d440: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
d450: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  tal_changes()] f
d460: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69  unction.** to fi
d470: 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  nd the total num
d480: 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69  ber of changes i
d490: 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73  ncluding changes
d4a0: 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67   caused by trigg
d4b0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f  ers..**.** A "ro
d4c0: 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63  w change" is a c
d4d0: 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c  hange to a singl
d4e0: 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c  e row of a singl
d4f0: 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65  e table.** cause
d500: 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20  d by an INSERT, 
d510: 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54  DELETE, or UPDAT
d520: 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f  E statement.  Ro
d530: 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  ws that.** are c
d540: 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65  hanged as side e
d550: 66 66 65 63 74 73 20 6f 66 20 52 45 50 4c 41 43  ffects of REPLAC
d560: 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  E constraint res
d570: 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c  olution,.** roll
d580: 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63  back, ABORT proc
d590: 65 73 73 69 6e 67 2c 20 44 52 4f 50 20 54 41 42  essing, DROP TAB
d5a0: 4c 45 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74  LE, or by any ot
d5b0: 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d  her.** mechanism
d5c0: 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
d5d0: 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  s direct row cha
d5e0: 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74  nges..**.** A "t
d5f0: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20  rigger context" 
d600: 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78  is a scope of ex
d610: 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67  ecution that beg
d620: 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20  ins and.** ends 
d630: 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20  with the script 
d640: 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 4d  of a trigger.  M
d650: 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ost SQL statemen
d660: 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61  ts are.** evalua
d670: 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61  ted outside of a
d680: 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69  ny trigger.  Thi
d690: 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65  s is the "top le
d6a0: 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20  vel".** trigger 
d6b0: 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74  context.  If a t
d6c0: 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f  rigger fires fro
d6d0: 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
d6e0: 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65   a.** new trigge
d6f0: 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74  r context is ent
d700: 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72  ered for the dur
d710: 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e  ation of that on
d720: 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53  e.** trigger.  S
d730: 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74  ubtriggers creat
d740: 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f  e subcontexts fo
d750: 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e  r their duration
d760: 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20  ..**.** Calling 
d770: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
d780: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   or [sqlite3_ste
d790: 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79  p()] recursively
d7a0: 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65   does.** not cre
d7b0: 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65  ate a new trigge
d7c0: 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
d7d0: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   This function r
d7e0: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
d7f0: 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20  r of direct row 
d800: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a  changes in the.*
d810: 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  * most recent IN
d820: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
d830: 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
d840: 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  t within the sam
d850: 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e  e.** trigger con
d860: 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73  text..**.** Thus
d870: 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72  , when called fr
d880: 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
d890: 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  , this function 
d8a0: 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e  returns the.** n
d8b0: 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
d8c0: 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
d8d0: 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
d8e0: 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
d8f0: 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72   that also occur
d900: 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c  red at the top l
d910: 65 76 65 6c 2e 20 20 57 69 74 68 69 6e 20 74 68  evel.  Within th
d920: 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67  e body of a trig
d930: 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69  ger,.** the sqli
d940: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  te3_changes() in
d950: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63  terface can be c
d960: 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68  alled to find th
d970: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
d980: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
d990: 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
d9a0: 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
d9b0: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
d9c0: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ** statement wit
d9d0: 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
d9e0: 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
d9f0: 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
da00: 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65  e number returne
da10: 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  d does not inclu
da20: 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61  de changes.** ca
da30: 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67  used by subtrigg
da40: 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20  ers since those 
da50: 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63  have their own c
da60: 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51  ontext..**.** SQ
da70: 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
da80: 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c  the command "DEL
da90: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
daa0: 77 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20  without a WHERE 
dab0: 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f  clause.** by dro
dac0: 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61  pping and recrea
dad0: 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20  ting the table. 
dae0: 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 20 66   (This is much f
daf0: 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67  aster than going
db00: 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20  .** through and 
db10: 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64  deleting individ
db20: 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f  ual elements fro
db30: 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42  m the table.)  B
db40: 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a  ecause of this.*
db50: 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20  * optimization, 
db60: 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e  the deletions in
db70: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
db80: 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77  ble" are not row
db90: 20 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a 2a 20   changes and.** 
dba0: 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e  will not be coun
dbb0: 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
dbc0: 65 33 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20  e3_changes() or 
dbd0: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
dbe0: 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66 75 6e  hanges()].** fun
dbf0: 63 74 69 6f 6e 73 2c 20 72 65 67 61 72 64 6c 65  ctions, regardle
dc00: 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ss of the number
dc10: 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61   of elements tha
dc20: 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c  t were originall
dc30: 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61 62 6c  y.** in the tabl
dc40: 65 2e 20 20 54 6f 20 67 65 74 20 61 6e 20 61 63  e.  To get an ac
dc50: 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20  curate count of 
dc60: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
dc70: 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a  ws deleted, use.
dc80: 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  ** "DELETE FROM 
dc90: 74 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69  table WHERE 1" i
dca0: 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  nstead..**.** IN
dcb0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
dcc0: 7b 46 31 32 32 34 31 7d 20 54 68 65 20 5b 73 71  {F12241} The [sq
dcd0: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
dce0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
dcf0: 72 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  return the numbe
dd00: 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  r of.**         
dd10: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
dd20: 73 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  sed by the most 
dd30: 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
dd40: 50 44 41 54 45 2c 0a 2a 2a 20 20 20 20 20 20 20  PDATE,.**       
dd50: 20 20 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61     or DELETE sta
dd60: 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 73 61  tement on the sa
dd70: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
dd80: 65 63 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20  ection and.**   
dd90: 20 20 20 20 20 20 20 77 69 74 68 69 6e 20 74 68         within th
dda0: 65 20 73 61 6d 65 20 6f 72 20 68 69 67 68 65 72  e same or higher
ddb0: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
ddc0: 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65  , or zero if the
ddd0: 72 65 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20  re have.**      
dde0: 20 20 20 20 6e 6f 74 20 62 65 65 6e 20 61 6e 79      not been any
ddf0: 20 71 75 61 6c 69 66 79 69 6e 67 20 72 6f 77 20   qualifying row 
de00: 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b  changes..**.** {
de10: 46 31 32 32 34 33 7d 20 53 74 61 74 65 6d 65 6e  F12243} Statemen
de20: 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  ts of the form "
de30: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
de40: 65 6e 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a  ename" with no.*
de50: 2a 20 20 20 20 20 20 20 20 20 20 57 48 45 52 45  *          WHERE
de60: 20 63 6c 61 75 73 65 20 73 68 61 6c 6c 20 63 61   clause shall ca
de70: 75 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 63  use subsequent c
de80: 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20  alls to.**      
de90: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 68 61      [sqlite3_cha
dea0: 6e 67 65 73 28 29 5d 20 74 6f 20 72 65 74 75 72  nges()] to retur
deb0: 6e 20 7a 65 72 6f 2c 20 72 65 67 61 72 64 6c 65  n zero, regardle
dec0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  ss of the.**    
ded0: 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
dee0: 72 6f 77 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20  rows originally 
def0: 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 0a 2a 2a  in the table..**
df00: 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a  .** LIMITATIONS:
df10: 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 32 35 32 7d 20  .**.** {U12252} 
df20: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
df30: 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
df40: 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
df50: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
df60: 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  on.**          w
df70: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68  hile [sqlite3_ch
df80: 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
df90: 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
dfa0: 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20  ue returned.**  
dfb0: 20 20 20 20 20 20 20 20 69 73 20 75 6e 70 72 65          is unpre
dfc0: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
dfd0: 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
dfe0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
dff0: 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
e000: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e010: 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
e020: 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 46  Rows Modified {F
e030: 31 32 32 36 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69  12260}.**.** Thi
e040: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
e050: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
e060: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
e070: 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c 0a 2a  sed by INSERT,.*
e080: 2a 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  * UPDATE or DELE
e090: 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69  TE statements si
e0a0: 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73  nce the [databas
e0b0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61  e connection] wa
e0c0: 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54 68 65  s opened..** The
e0d0: 20 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65 73 20   count includes 
e0e0: 61 6c 6c 20 63 68 61 6e 67 65 73 20 66 72 6f 6d  all changes from
e0f0: 20 61 6c 6c 20 74 72 69 67 67 65 72 20 63 6f 6e   all trigger con
e100: 74 65 78 74 73 2e 20 20 48 6f 77 65 76 65 72 2c  texts.  However,
e110: 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f  .** the count do
e120: 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
e130: 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69  hanges used to i
e140: 6d 70 6c 65 6d 65 6e 74 20 52 45 50 4c 41 43 45  mplement REPLACE
e150: 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a   constraints,.**
e160: 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72   do rollbacks or
e170: 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
e180: 67 2c 20 6f 72 20 44 52 4f 50 20 74 61 62 6c 65  g, or DROP table
e190: 20 70 72 6f 63 65 73 73 69 6e 67 2e 0a 2a 2a 20   processing..** 
e1a0: 54 68 65 20 63 68 61 6e 67 65 73 20 61 72 65 20  The changes are 
e1b0: 63 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20  counted as soon 
e1c0: 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
e1d0: 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d   that makes them
e1e0: 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64   is.** completed
e1f0: 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65   (when the state
e200: 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69 73 20 70  ment handle is p
e210: 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
e220: 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
e230: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
e240: 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51  ze()])..**.** SQ
e250: 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
e260: 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c  the command "DEL
e270: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
e280: 77 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20  without a WHERE 
e290: 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f  clause.** by dro
e2a0: 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61  pping and recrea
e2b0: 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20  ting the table. 
e2c0: 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 20 66   (This is much f
e2d0: 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67  aster than going
e2e0: 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20  .** through and 
e2f0: 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64  deleting individ
e300: 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f  ual elements fro
e310: 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42  m the table.)  B
e320: 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a  ecause of this.*
e330: 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20  * optimization, 
e340: 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e  the deletions in
e350: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
e360: 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77  ble" are not row
e370: 20 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a 2a 20   changes and.** 
e380: 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e  will not be coun
e390: 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
e3a0: 65 33 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20  e3_changes() or 
e3b0: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
e3c0: 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66 75 6e  hanges()].** fun
e3d0: 63 74 69 6f 6e 73 2c 20 72 65 67 61 72 64 6c 65  ctions, regardle
e3e0: 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ss of the number
e3f0: 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61   of elements tha
e400: 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c  t were originall
e410: 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61 62 6c  y.** in the tabl
e420: 65 2e 20 20 54 6f 20 67 65 74 20 61 6e 20 61 63  e.  To get an ac
e430: 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20  curate count of 
e440: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
e450: 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a  ws deleted, use.
e460: 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  ** "DELETE FROM 
e470: 74 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69  table WHERE 1" i
e480: 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 53 65  nstead..**.** Se
e490: 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
e4a0: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
e4b0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
e4c0: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
e4d0: 2a 20 7b 46 31 32 32 36 31 7d 20 54 68 65 20 5b  * {F12261} The [
e4e0: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
e4f0: 61 6e 67 65 73 28 29 5d 20 72 65 74 75 72 6e 73  anges()] returns
e500: 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
e510: 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  r.**          of
e520: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
e530: 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c 20 55  sed by INSERT, U
e540: 50 44 41 54 45 2c 20 61 6e 64 2f 6f 72 20 44 45  PDATE, and/or DE
e550: 4c 45 54 45 0a 2a 2a 20 20 20 20 20 20 20 20 20  LETE.**         
e560: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 74   statements on t
e570: 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
e580: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 69  e connection], i
e590: 6e 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 20 20  n any.**        
e5a0: 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78    trigger contex
e5b0: 74 2c 20 73 69 6e 63 65 20 74 68 65 20 64 61 74  t, since the dat
e5c0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e5d0: 20 77 61 73 20 63 72 65 61 74 65 64 2e 0a 2a 2a   was created..**
e5e0: 0a 2a 2a 20 7b 46 31 32 32 36 33 7d 20 53 74 61  .** {F12263} Sta
e5f0: 74 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 66  tements of the f
e600: 6f 72 6d 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  orm "DELETE FROM
e610: 20 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 74 68   tablename" with
e620: 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   no.**          
e630: 57 48 45 52 45 20 63 6c 61 75 73 65 20 73 68 61  WHERE clause sha
e640: 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  ll not change th
e650: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
e660: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20  .**          by 
e670: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
e680: 68 61 6e 67 65 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a  hanges()]..**.**
e690: 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a   LIMITATIONS:.**
e6a0: 0a 2a 2a 20 7b 55 31 32 32 36 34 7d 20 49 66 20  .** {U12264} If 
e6b0: 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
e6c0: 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
e6d0: 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
e6e0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
e6f0: 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 6c  **          whil
e700: 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
e710: 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
e720: 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
e730: 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20  value.**        
e740: 20 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e    returned is un
e750: 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
e760: 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
e770: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
e780: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
e790: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
e7a0: 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
e7b0: 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
e7c0: 67 20 51 75 65 72 79 20 7b 46 31 32 32 37 30 7d  g Query {F12270}
e7d0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
e7e0: 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
e7f0: 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
e800: 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
e810: 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
e820: 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
e830: 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
e840: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
e850: 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
e860: 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
e870: 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
e880: 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
e890: 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
e8a0: 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
e8b0: 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
e8c0: 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
e8d0: 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
e8e0: 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
e8f0: 20 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63   It is safe to c
e900: 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
e910: 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
e920: 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
e930: 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
e940: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
e950: 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
e960: 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
e970: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
e980: 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
e990: 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
e9a0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e9b0: 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
e9c0: 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
e9d0: 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
e9e0: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
e9f0: 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
ea00: 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72  * If an SQL oper
ea10: 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
ea20: 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
ea30: 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
ea40: 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
ea50: 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
ea60: 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
ea70: 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
ea80: 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
ea90: 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
eaa0: 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
eab0: 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
eac0: 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 61  .** An SQL opera
ead0: 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
eae0: 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
eaf0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
eb00: 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 74  ERRUPT]..** If t
eb10: 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
eb20: 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
eb30: 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
eb40: 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
eb50: 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
eb60: 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
eb70: 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
eb80: 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
eb90: 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
eba0: 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
ebb0: 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
ebc0: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
ebd0: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 68 61  3_interrupt() ha
ebe0: 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
ebf0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
ec00: 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
ec10: 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
ec20: 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
ec30: 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  rns..**.** INVAR
ec40: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
ec50: 32 32 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2271} The [sqlit
ec60: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20  e3_interrupt()] 
ec70: 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 66  interface will f
ec80: 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e 69 6e 67  orce all running
ec90: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
eca0: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
ecb0: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
ecc0: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
ecd0: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
ece0: 20 20 20 20 20 74 6f 20 68 61 6c 74 20 61 66 74       to halt aft
ecf0: 65 72 20 70 72 6f 63 65 73 73 69 6e 67 20 61 74  er processing at
ed00: 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64 69 74 69   most one additi
ed10: 6f 6e 61 6c 20 72 6f 77 20 6f 66 20 64 61 74 61  onal row of data
ed20: 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 37 32 7d  ..**.** {F12272}
ed30: 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65   Any SQL stateme
ed40: 6e 74 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  nt that is inter
ed50: 72 75 70 74 65 64 20 62 79 20 5b 73 71 6c 69 74  rupted by [sqlit
ed60: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
ed70: 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c  **          will
ed80: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
ed90: 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a  INTERRUPT]..**.*
eda0: 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a  * LIMITATIONS:.*
edb0: 2a 0a 2a 2a 20 7b 55 31 32 32 37 39 7d 20 49 66  *.** {U12279} If
edc0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
edd0: 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
ede0: 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
edf0: 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20  nterrupt()].**  
ee00: 20 20 20 20 20 20 20 20 69 73 20 72 75 6e 6e 69          is runni
ee10: 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e  ng then bad thin
ee20: 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68  gs will likely h
ee30: 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73  appen..*/.void s
ee40: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
ee50: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
ee60: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
ee70: 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
ee80: 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
ee90: 6d 70 6c 65 74 65 20 7b 46 31 30 35 31 30 7d 0a  mplete {F10510}.
eea0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
eeb0: 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
eec0: 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  for command-line
eed0: 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
eee0: 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
eef0: 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
ef00: 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
ef10: 72 6d 20 63 6f 6d 70 6c 65 74 65 20 61 20 53 51  rm complete a SQ
ef20: 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
ef30: 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
ef40: 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
ef50: 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
ef60: 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
ef70: 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
ef80: 6e 67 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ng.  These routi
ef90: 6e 65 73 20 72 65 74 75 72 6e 20 74 72 75 65 20  nes return true 
efa0: 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
efb0: 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
efc0: 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
efd0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
efe0: 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
eff0: 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
f000: 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
f010: 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
f020: 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
f030: 20 6e 6f 74 20 61 20 66 72 61 67 6d 65 6e 74 20   not a fragment 
f040: 6f 66 20 61 0a 2a 2a 20 43 52 45 41 54 45 20 54  of a.** CREATE T
f050: 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
f060: 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68  .  Semicolons th
f070: 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
f080: 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
f090: 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
f0a0: 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
f0b0: 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
f0c0: 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
f0d0: 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
f0e0: 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
f0f0: 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
f100: 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
f110: 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
f120: 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
f130: 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
f140: 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
f150: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
f160: 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65  do not parse the
f170: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
f180: 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74  thus.** will not
f190: 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69   detect syntacti
f1a0: 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20  cally incorrect 
f1b0: 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  SQL..**.** INVAR
f1c0: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
f1d0: 30 35 31 31 7d 20 54 68 65 20 73 71 6c 69 74 65  0511} The sqlite
f1e0: 33 5f 63 6f 6d 70 6c 65 74 65 28 29 20 61 6e 64  3_complete() and
f1f0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
f200: 65 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  e16() functions.
f210: 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
f220: 72 6e 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  rn true (non-zer
f230: 6f 29 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  o) if and only i
f240: 66 20 74 68 65 20 6c 61 73 74 20 6e 6f 6e 2d 77  f the last non-w
f250: 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 20 20 20  hitespace.**    
f260: 20 20 20 20 20 20 74 6f 6b 65 6e 20 69 6e 20 74        token in t
f270: 68 65 69 72 20 69 6e 70 75 74 20 69 73 20 61 20  heir input is a 
f280: 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61 74 20 69  semicolon that i
f290: 73 20 6e 6f 74 20 69 6e 20 62 65 74 77 65 65 6e  s not in between
f2a0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
f2b0: 20 42 45 47 49 4e 20 61 6e 64 20 45 4e 44 20 6f   BEGIN and END o
f2c0: 66 20 61 20 43 52 45 41 54 45 20 54 52 49 47 47  f a CREATE TRIGG
f2d0: 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  ER statement..**
f2e0: 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a  .** LIMITATIONS:
f2f0: 0a 2a 2a 0a 2a 2a 20 7b 55 31 30 35 31 32 7d 20  .**.** {U10512} 
f300: 54 68 65 20 69 6e 70 75 74 20 74 6f 20 73 71 6c  The input to sql
f310: 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 20  ite3_complete() 
f320: 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
f330: 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20  erminated.**    
f340: 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69        UTF-8 stri
f350: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 55 31 30 35 31  ng..**.** {U1051
f360: 33 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  3} The input to 
f370: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
f380: 31 36 28 29 20 6d 75 73 74 20 62 65 20 61 20 7a  16() must be a z
f390: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
f3a0: 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 31  *          UTF-1
f3b0: 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
f3c0: 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
f3d0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
f3e0: 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
f3f0: 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c  r *sql);.int sql
f400: 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
f410: 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
f420: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
f430: 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
f440: 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
f450: 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
f460: 6f 72 73 20 7b 46 31 32 33 31 30 7d 0a 2a 2a 0a  ors {F12310}.**.
f470: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
f480: 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
f490: 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69  function that mi
f4a0: 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
f4b0: 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
f4c0: 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
f4d0: 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65   open a database
f4e0: 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74   table that anot
f4f0: 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
f500: 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63   process has loc
f510: 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ked..**.** If th
f520: 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
f530: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
f540: 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
f550: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
f560: 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75  CKED].** is retu
f570: 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
f580: 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69   upon encounteri
f590: 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 49 66 20  ng the lock. If 
f5a0: 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
f5b0: 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  k.** is not NULL
f5c0: 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  , then the callb
f5d0: 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f  ack will be invo
f5e0: 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
f5f0: 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  uments..**.** Th
f600: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
f610: 20 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20   to the handler 
f620: 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
f630: 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
f640: 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
f650: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
f660: 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
f670: 6e 64 6c 65 72 28 29 2e 20 20 54 68 65 20 73 65  ndler().  The se
f680: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
f690: 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
f6a0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
f6b0: 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
f6c0: 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
f6d0: 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
f6e0: 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  n invoked for th
f6f0: 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  is locking event
f700: 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 73  .  If the.** bus
f710: 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
f720: 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
f730: 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
f740: 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
f750: 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
f760: 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
f770: 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
f780: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
f790: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
f7a0: 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   If the callback
f7b0: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
f7c0: 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20  o, then another 
f7d0: 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61  attempt.** is ma
f7e0: 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  de to open the d
f7f0: 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64  atabase for read
f800: 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c  ing and the cycl
f810: 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a  e repeats..**.**
f820: 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   The presence of
f830: 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
f840: 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  does not guarant
f850: 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20  ee that it will 
f860: 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68  be invoked.** wh
f870: 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b  en there is lock
f880: 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49 66 20   contention. If 
f890: 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
f8a0: 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
f8b0: 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
f8c0: 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
f8d0: 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
f8e0: 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
f8f0: 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
f900: 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20  ITE_BUSY].** or 
f910: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
f920: 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f  OCKED] instead o
f930: 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  f invoking the b
f940: 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
f950: 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
f960: 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
f970: 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
f980: 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
f990: 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
f9a0: 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
f9b0: 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
f9c0: 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
f9d0: 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
f9e0: 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
f9f0: 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
fa00: 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
fa10: 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
fa20: 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
fa30: 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
fa40: 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
fa50: 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
fa60: 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
fa70: 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
fa80: 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
fa90: 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
faa0: 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
fab0: 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
fac0: 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
fad0: 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
fae0: 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
faf0: 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
fb00: 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
fb10: 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
fb20: 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
fb30: 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
fb40: 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
fb50: 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
fb60: 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
fb70: 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
fb80: 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
fb90: 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
fba0: 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
fbb0: 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
fbc0: 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  proceed..**.** T
fbd0: 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
fbe0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
fbf0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
fc00: 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20  ITE_BUSY] error 
fc10: 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  is converted to 
fc20: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
fc30: 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53  OCKED].** when S
fc40: 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20  QLite is in the 
fc50: 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67  middle of a larg
fc60: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68  e transaction wh
fc70: 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63  ere all the.** c
fc80: 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20  hanges will not 
fc90: 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d  fit into the in-
fca0: 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53  memory cache.  S
fcb0: 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c  QLite will.** al
fcc0: 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53  ready hold a RES
fcd0: 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68  ERVED lock on th
fce0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
fcf0: 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a   but it needs.**
fd00: 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73   to promote this
fd10: 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49   lock to EXCLUSI
fd20: 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61  VE so that it ca
fd30: 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a  n spill cache.**
fd40: 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20   pages into the 
fd50: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
fd60: 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f  thout harm to co
fd70: 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64  ncurrent.** read
fd80: 65 72 73 2e 20 20 49 66 20 69 74 20 69 73 20 75  ers.  If it is u
fd90: 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65  nable to promote
fda0: 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20   the lock, then 
fdb0: 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  the in-memory.**
fdc0: 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c   cache will be l
fdd0: 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73  eft in an incons
fde0: 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64  istent state and
fdf0: 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   so the error.**
fe00: 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65   code is promote
fe10: 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74  d from the relat
fe20: 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51  ively benign [SQ
fe30: 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a  LITE_BUSY] to.**
fe40: 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65   the more severe
fe50: 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
fe60: 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 65  LOCKED].  This e
fe70: 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74  rror code promot
fe80: 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e  ion.** forces an
fe90: 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62   automatic rollb
fea0: 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67  ack of the chang
feb0: 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  es.  See the.** 
fec0: 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61  <a href="/cvstra
fed0: 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74  c/wiki?p=Corrupt
fee0: 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
fef0: 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75  Error">.** Corru
ff00: 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
ff10: 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69  syError</a> wiki
ff20: 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63   page for a disc
ff30: 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a  ussion of why.**
ff40: 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61   this is importa
ff50: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  nt..**.** There 
ff60: 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
ff70: 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
ff80: 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
ff90: 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
ffa0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
ffb0: 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
ffc0: 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
ffd0: 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
ffe0: 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 20 20  y set handler.  
fff0: 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
10000 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
10010 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
10020 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
10030 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
10040 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ndler..**.** INV
10050 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
10060 46 31 32 33 31 31 7d 20 54 68 65 20 5b 73 71 6c  F12311} The [sql
10070 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
10080 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65  r()] function re
10090 70 6c 61 63 65 73 20 74 68 65 20 62 75 73 79 20  places the busy 
100a0 68 61 6e 64 6c 65 72 0a 2a 2a 20 20 20 20 20 20  handler.**      
100b0 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 69 6e 20      callback in 
100c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
100d0 6e 65 63 74 69 6f 6e 20 69 64 65 6e 74 69 66 69  nection identifi
100e0 65 64 20 62 79 20 74 68 65 20 31 73 74 0a 2a 2a  ed by the 1st.**
100f0 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65            parame
10100 74 65 72 20 77 69 74 68 20 61 20 6e 65 77 20 62  ter with a new b
10110 75 73 79 20 68 61 6e 64 6c 65 72 20 69 64 65 6e  usy handler iden
10120 74 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e  tified by the 2n
10130 64 20 61 6e 64 20 33 72 64 0a 2a 2a 20 20 20 20  d and 3rd.**    
10140 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 73        parameters
10150 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 32 7d  ..**.** {F12312}
10160 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73   The default bus
10170 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 6e 65  y handler for ne
10180 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
10190 63 74 69 6f 6e 73 20 69 73 20 4e 55 4c 4c 2e 0a  ctions is NULL..
101a0 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 34 7d 20 57  **.** {F12314} W
101b0 68 65 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20  hen two or more 
101c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
101d0 69 6f 6e 20 73 68 61 72 65 20 61 0a 2a 2a 20 20  ion share a.**  
101e0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
101f0 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
10200 61 63 68 65 20 7c 20 63 6f 6d 6d 6f 6e 20 63 61  ache | common ca
10210 63 68 65 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  che],.**        
10220 20 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c    the busy handl
10230 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  er for the datab
10240 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
10250 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 0a 2a  urrently using.*
10260 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63  *          the c
10270 61 63 68 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  ache is invoked 
10280 77 68 65 6e 20 74 68 65 20 63 61 63 68 65 20 65  when the cache e
10290 6e 63 6f 75 6e 74 65 72 73 20 61 20 6c 6f 63 6b  ncounters a lock
102a0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 33 31 36 7d  ..**.** {F12316}
102b0 20 49 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   If a busy handl
102c0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
102d0 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74  rns zero, then t
102e0 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  he SQLite interf
102f0 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ace.**          
10300 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68  that provoked th
10310 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 20  e locking event 
10320 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
10330 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a  ITE_BUSY]..**.**
10340 20 7b 46 31 32 33 31 38 7d 20 53 51 4c 69 74 65   {F12318} SQLite
10350 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 73 20 74 68   will invokes th
10360 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77  e busy handler w
10370 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
10380 73 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20 20  s which.**      
10390 20 20 20 20 61 72 65 20 61 20 63 6f 70 79 20 6f      are a copy o
103a0 66 20 74 68 65 20 70 6f 69 6e 74 65 72 20 73 75  f the pointer su
103b0 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 33 72  pplied by the 3r
103c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
103d0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
103e0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
103f0 28 29 5d 20 61 6e 64 20 61 20 63 6f 75 6e 74 20  ()] and a count 
10400 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
10410 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20   prior.**       
10420 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f     invocations o
10430 66 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  f the busy handl
10440 65 72 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  er for the same 
10450 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 0a 2a  locking event..*
10460 2a 0a 2a 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53  *.** LIMITATIONS
10470 3a 0a 2a 2a 0a 2a 2a 20 7b 55 31 32 33 31 39 7d  :.**.** {U12319}
10480 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   A busy handler 
10490 73 68 6f 75 6c 64 20 6e 6f 74 20 63 6c 6f 73 65  should not close
104a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
104b0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
104c0 20 20 20 20 20 6f 72 20 5b 70 72 65 70 61 72 65       or [prepare
104d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
104e0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
104f0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69  sy handler..*/.i
10500 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
10510 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
10520 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  , int(*)(void*,i
10530 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  nt), void*);../*
10540 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
10550 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
10560 20 7b 46 31 32 33 34 30 7d 0a 2a 2a 0a 2a 2a 20   {F12340}.**.** 
10570 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
10580 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
10590 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
105a0 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
105b0 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
105c0 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
105d0 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
105e0 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
105f0 20 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20   The handler.** 
10600 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
10610 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
10620 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
10630 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
10640 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
10650 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b 46 31 32  ccumulated. {F12
10660 33 34 33 7d 20 41 66 74 65 72 20 22 6d 73 22 20  343} After "ms" 
10670 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
10680 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
10690 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
106a0 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
106b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
106c0 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
106d0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
106e0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
106f0 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  CKED]..**.** Cal
10700 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
10710 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
10720 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
10730 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
10740 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
10750 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
10760 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e  .** There can on
10770 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
10780 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
10790 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
107a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
107b0 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69  tion] any any gi
107c0 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
107d0 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
107e0 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
107f0 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
10800 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
10810 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
10820 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
10830 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
10840 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
10850 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a 2a  is cleared..**.*
10860 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
10870 0a 2a 2a 20 7b 46 31 32 33 34 31 7d 20 54 68 65  .** {F12341} The
10880 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
10890 69 6d 65 6f 75 74 28 29 5d 20 66 75 6e 63 74 69  imeout()] functi
108a0 6f 6e 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79  on overrides any
108b0 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20   prior.**       
108c0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79     [sqlite3_busy
108d0 5f 74 69 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b  _timeout()] or [
108e0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
108f0 64 6c 65 72 28 29 5d 20 73 65 74 74 69 6e 67 0a  dler()] setting.
10900 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74  **          on t
10910 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
10920 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a   connection..**.
10930 2a 2a 20 7b 46 31 32 33 34 33 7d 20 49 66 20 74  ** {F12343} If t
10940 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
10950 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73   to [sqlite3_bus
10960 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20  y_timeout()] is 
10970 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20  less than.**    
10980 20 20 20 20 20 20 6f 72 20 65 71 75 61 6c 20 74        or equal t
10990 6f 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  o zero, then the
109a0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
109b0 20 63 6c 65 61 72 65 64 20 73 6f 20 74 68 61 74   cleared so that
109c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c  .**          all
109d0 20 73 75 62 73 65 71 75 65 6e 74 20 6c 6f 63 6b   subsequent lock
109e0 69 6e 67 20 65 76 65 6e 74 73 20 69 6d 6d 65 64  ing events immed
109f0 69 61 74 65 6c 79 20 72 65 74 75 72 6e 20 5b 53  iately return [S
10a00 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a  QLITE_BUSY]..**.
10a10 2a 2a 20 7b 46 31 32 33 34 34 7d 20 49 66 20 74  ** {F12344} If t
10a20 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
10a30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73   to [sqlite3_bus
10a40 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20  y_timeout()] is 
10a50 61 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20  a positive.**   
10a60 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 4e 2c         number N,
10a70 20 74 68 65 6e 20 61 20 62 75 73 79 20 68 61 6e   then a busy han
10a80 64 6c 65 72 20 69 73 20 73 65 74 20 74 68 61 74  dler is set that
10a90 20 72 65 70 65 61 74 65 64 6c 79 20 63 61 6c 6c   repeatedly call
10aa0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
10ab0 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
10ac0 64 20 69 6e 20 74 68 65 20 56 46 53 20 69 6e 74  d in the VFS int
10ad0 65 72 66 61 63 65 20 75 6e 74 69 6c 20 65 69 74  erface until eit
10ae0 68 65 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  her the.**      
10af0 20 20 20 20 6c 6f 63 6b 20 63 6c 65 61 72 73 20      lock clears 
10b00 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 63 75 6d  or until the cum
10b10 75 6c 61 74 69 76 65 20 73 6c 65 65 70 20 74 69  ulative sleep ti
10b20 6d 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  me reported back
10b30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20  .**          by 
10b40 78 53 6c 65 65 70 28 29 20 65 78 63 65 65 64 73  xSleep() exceeds
10b50 20 4e 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e   N milliseconds.
10b60 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
10b70 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c  busy_timeout(sql
10b80 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a  ite3*, int ms);.
10b90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10ba0 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75   Convenience Rou
10bb0 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e  tines For Runnin
10bc0 67 20 51 75 65 72 69 65 73 20 7b 46 31 32 33 37  g Queries {F1237
10bd0 30 7d 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  0}.**.** Definit
10be0 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
10bf0 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
10c00 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
10c10 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
10c20 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
10c30 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
10c40 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
10c50 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
10c60 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
10c70 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
10c80 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
10c90 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
10ca0 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
10cb0 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
10cc0 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
10cd0 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
10ce0 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
10cf0 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
10d00 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
10d10 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
10d20 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
10d30 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
10d40 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
10d50 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
10d60 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
10d70 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
10d80 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
10d90 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
10da0 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
10db0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
10dc0 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
10dd0 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
10de0 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
10df0 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
10e00 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
10e10 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
10e20 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
10e30 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
10e40 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
10e50 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
10e60 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
10e70 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
10e80 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
10e90 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
10ea0 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
10eb0 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
10ec0 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
10ed0 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
10ee0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
10ef0 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
10f00 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
10f10 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
10f20 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
10f30 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
10f40 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
10f50 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
10f60 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
10f70 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
10f80 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
10f90 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
10fa0 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
10fb0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
10fc0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
10fd0 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
10fe0 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
10ff0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
11000 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20  )]..**.** As an 
11010 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
11020 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
11030 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
11040 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
11050 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
11060 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
11070 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
11080 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
11090 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
110a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
110b0 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
110c0 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
110d0 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
110e0 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
110f0 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
11100 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
11110 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
11120 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
11130 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
11140 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
11150 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
11160 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
11170 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
11180 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
11190 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
111a0 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
111b0 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
111c0 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
111d0 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
111e0 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
111f0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
11200 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
11210 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
11220 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
11230 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
11240 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
11250 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
11260 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
11270 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
11280 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
11290 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
112a0 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
112b0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
112c0 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
112d0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
112e0 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
112f0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
11300 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
11310 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
11320 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
11330 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
11340 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
11350 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
11360 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
11370 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
11380 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
11390 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
113a0 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
113b0 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
113c0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 74 20   parameter.  It 
113d0 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
113e0 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a   table to the.**
113f0 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69   pointer given i
11400 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  n its 3rd parame
11410 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ter..**.** After
11420 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
11430 63 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ction has finish
11440 65 64 20 75 73 69 6e 67 20 74 68 65 20 72 65 73  ed using the res
11450 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64 0a 2a  ult, it should.*
11460 2a 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  * pass the point
11470 65 72 20 74 6f 20 74 68 65 20 72 65 73 75 6c 74  er to the result
11480 20 74 61 62 6c 65 20 74 6f 20 73 71 6c 69 74 65   table to sqlite
11490 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
114a0 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
114b0 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
114c0 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
114d0 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
114e0 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
114f0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
11500 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
11510 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
11520 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
11530 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
11540 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
11550 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
11560 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
11570 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
11580 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
11590 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
115a0 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
115b0 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
115c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
115d0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
115e0 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
115f0 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
11600 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
11610 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
11620 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
11630 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
11640 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
11650 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
11660 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
11670 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
11680 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
11690 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
116a0 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
116b0 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
116c0 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
116d0 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
116e0 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
116f0 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
11700 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
11710 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
11720 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
11730 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
11740 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
11750 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
11760 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
11770 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  errmsg()]..**.**
11780 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
11790 2a 2a 20 7b 46 31 32 33 37 31 7d 20 49 66 20 61  ** {F12371} If a
117a0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
117b0 62 6c 65 28 29 5d 20 66 61 69 6c 73 20 61 20 6d  ble()] fails a m
117c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
117d0 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
117e0 20 20 20 69 74 20 66 72 65 65 73 20 74 68 65 20     it frees the 
117f0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 75 6e 64  result table und
11800 65 72 20 63 6f 6e 73 74 72 75 63 74 69 6f 6e 2c  er construction,
11810 20 61 62 6f 72 74 73 20 74 68 65 0a 2a 2a 20 20   aborts the.**  
11820 20 20 20 20 20 20 20 20 71 75 65 72 79 20 69 6e          query in
11830 20 70 72 6f 63 65 73 73 2c 20 73 6b 69 70 73 20   process, skips 
11840 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 71  any subsequent q
11850 75 65 72 69 65 73 2c 20 73 65 74 73 20 74 68 65  ueries, sets the
11860 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 72 65  .**          *re
11870 73 75 6c 74 70 20 6f 75 74 70 75 74 20 70 6f 69  sultp output poi
11880 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 61 6e 64  nter to NULL and
11890 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
118a0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  _NOMEM]..**.** {
118b0 46 31 32 33 37 33 7d 20 49 66 20 74 68 65 20 6e  F12373} If the n
118c0 63 6f 6c 75 6d 6e 20 70 61 72 61 6d 65 74 65 72  column parameter
118d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74   to [sqlite3_get
118e0 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74  _table()] is not
118f0 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20   NULL.**        
11900 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
11910 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 77 72 69  get_table()] wri
11920 74 65 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  tes the number o
11930 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
11940 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73  .**          res
11950 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20 71  ult set of the q
11960 75 65 72 79 20 69 6e 74 6f 20 2a 6e 63 6f 6c 75  uery into *ncolu
11970 6d 6e 20 69 66 20 74 68 65 20 71 75 65 72 79 20  mn if the query 
11980 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  is.**          s
11990 75 63 63 65 73 73 66 75 6c 20 28 69 66 20 74 68  uccessful (if th
119a0 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  e function retur
119b0 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 29 2e 0a 2a  ns SQLITE_OK)..*
119c0 2a 0a 2a 2a 20 7b 46 31 32 33 37 34 7d 20 49 66  *.** {F12374} If
119d0 20 74 68 65 20 6e 72 6f 77 20 70 61 72 61 6d 65   the nrow parame
119e0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
119f0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  get_table()] is 
11a00 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20  not NULL.**     
11a10 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74       then [sqlit
11a20 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
11a30 77 72 69 74 65 73 20 74 68 65 20 6e 75 6d 62 65  writes the numbe
11a40 72 20 6f 66 20 72 6f 77 73 20 69 6e 20 74 68 65  r of rows in the
11a50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73  .**          res
11a60 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20 71  ult set of the q
11a70 75 65 72 79 20 69 6e 74 6f 20 2a 6e 72 6f 77 20  uery into *nrow 
11a80 69 66 20 74 68 65 20 71 75 65 72 79 20 69 73 0a  if the query is.
11a90 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75 63 63  **          succ
11aa0 65 73 73 66 75 6c 20 28 69 66 20 74 68 65 20 66  essful (if the f
11ab0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
11ac0 53 51 4c 49 54 45 5f 4f 4b 29 2e 0a 2a 2a 0a 2a  SQLITE_OK)..**.*
11ad0 2a 20 7b 46 31 32 33 37 36 7d 20 54 68 65 20 5b  * {F12376} The [
11ae0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
11af0 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 65  e()] function se
11b00 74 73 20 69 74 73 20 2a 6e 63 6f 6c 75 6d 6e 20  ts its *ncolumn 
11b10 76 61 6c 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20  value to the.** 
11b20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
11b30 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
11b40 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
11b50 74 68 65 20 71 75 65 72 79 20 69 6e 20 74 68 65  the query in the
11b60 20 73 71 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20   sql.**         
11b70 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 74   parameter, or t
11b80 6f 20 7a 65 72 6f 20 69 66 20 74 68 65 20 71 75  o zero if the qu
11b90 65 72 79 20 69 6e 20 73 71 6c 20 68 61 73 20 61  ery in sql has a
11ba0 6e 20 65 6d 70 74 79 20 72 65 73 75 6c 74 20 73  n empty result s
11bb0 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  et..*/.int sqlit
11bc0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
11bd0 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20  sqlite3*,       
11be0 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
11bf0 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
11c00 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst char *sql, 
11c10 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
11c20 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
11c30 20 63 68 61 72 20 2a 2a 2a 70 52 65 73 75 6c 74   char ***pResult
11c40 2c 20 20 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  ,      /* Result
11c50 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
11c60 2f 0a 20 20 69 6e 74 20 2a 6e 72 6f 77 2c 20 20  /.  int *nrow,  
11c70 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
11c80 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
11c90 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
11ca0 2a 2f 0a 20 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d  */.  int *ncolum
11cb0 6e 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  n,         /* Nu
11cc0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
11cd0 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
11ce0 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
11cf0 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 2f  errmsg         /
11d00 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
11d10 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
11d20 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
11d30 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
11d40 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
11d50 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
11d60 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
11d70 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46 31 37  g Functions {F17
11d80 34 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  400}.**.** These
11d90 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
11da0 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  rkalikes of the 
11db0 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
11dc0 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
11dd0 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
11de0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
11df0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
11e00 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
11e10 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
11e20 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
11e30 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
11e40 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
11e50 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
11e60 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
11e70 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
11e80 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
11e90 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
11ea0 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
11eb0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
11ec0 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 72  free()].  Both r
11ed0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
11ee0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
11ef0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
11f00 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
11f10 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
11f20 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
11f30 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
11f40 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
11f50 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70  * In sqlite3_snp
11f60 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
11f70 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
11f80 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
11f90 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
11fa0 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
11fb0 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
11fc0 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
11fd0 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
11fe0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
11ff0 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
12000 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
12010 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
12020 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
12030 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
12040 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
12050 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
12060 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
12070 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 61 6e  f().  This is an
12080 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61  .** historical a
12090 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e  ccident that can
120a0 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74  not be fixed wit
120b0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a  hout breaking.**
120c0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
120d0 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20  tibility.  Note 
120e0 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
120f0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
12100 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
12110 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
12120 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
12130 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
12140 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
12150 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
12160 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 64 6d   buffer.  We adm
12170 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
12180 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
12190 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
121a0 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
121b0 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
121c0 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
121d0 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
121e0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
121f0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
12200 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
12210 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
12220 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73  bility..**.** As
12230 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
12240 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
12250 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
12260 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
12270 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
12280 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
12290 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
122a0 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20  erminated.  The 
122b0 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
122c0 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
122d0 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
122e0 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
122f0 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
12300 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
12310 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
12320 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
12330 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
12340 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
12350 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
12360 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ers..**.** These
12370 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
12380 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
12390 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
123a0 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
123b0 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
123c0 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
123d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
123e0 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
123f0 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
12400 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
12410 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
12420 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
12430 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
12440 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
12450 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f  ..**.** The %q o
12460 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
12470 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73   %s in that it s
12480 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c  ubstitutes a nul
12490 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
124a0 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
124b0 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
124c0 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
124d0 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
124e0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
124f0 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
12500 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
12510 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79  ing literal.  By
12520 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27   doubling each '
12530 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  \''.** character
12540 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74   it escapes that
12550 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61   character and a
12560 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69  llows it to be i
12570 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20  nserted into.** 
12580 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  the string..**.*
12590 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61  * For example, a
125a0 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67  ssume the string
125b0 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20   variable zText 
125c0 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73  contains text as
125d0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
125e0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
125f0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78  >.**  char *zTex
12600 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70  t = "It's a happ
12610 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72  y day!";.** </pr
12620 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
12630 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73  **.** One can us
12640 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61  e this text in a
12650 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
12660 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
12670 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
12680 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
12690 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
126a0 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
126b0 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27  O table VALUES('
126c0 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  %q')", zText);.*
126d0 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
126e0 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
126f0 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
12700 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
12710 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
12720 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  e>.**.** Because
12730 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73   the %q format s
12740 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  tring is used, t
12750 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  he '\'' characte
12760 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73  r in zText.** is
12770 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65   escaped and the
12780 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69   SQL generated i
12790 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
127a0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
127b0 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
127c0 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
127d0 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70  UES('It''s a hap
127e0 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70  py day!').** </p
127f0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
12800 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63  .**.** This is c
12810 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20  orrect.  Had we 
12820 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20  used %s instead 
12830 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72  of %q, the gener
12840 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c  ated SQL.** woul
12850 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69  d have looked li
12860 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
12870 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12880 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
12890 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
128a0 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
128b0 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  !');.** </pre></
128c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
128d0 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78  * This second ex
128e0 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20  ample is an SQL 
128f0 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41  syntax error.  A
12900 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65  s a general rule
12910 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61   you should.** a
12920 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73  lways use %q ins
12930 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20  tead of %s when 
12940 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69  inserting text i
12950 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74  nto a string lit
12960 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eral..**.** The 
12970 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
12980 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
12990 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
129a0 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
129b0 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
129c0 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
129d0 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
129e0 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d  ly, if the param
129f0 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61  eter in the.** a
12a00 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20  rgument list is 
12a10 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
12a20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74  %Q substitutes t
12a30 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28  he text "NULL" (
12a40 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c  without.** singl
12a50 65 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61  e quotes) in pla
12a60 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74  ce of the %Q opt
12a70 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ion.  So, for ex
12a80 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
12a90 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
12aa0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
12ab0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
12ac0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
12ad0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
12ae0 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
12af0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
12b00 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
12b10 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
12b20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
12b30 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
12b40 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
12b50 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
12b60 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
12b70 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
12b80 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
12b90 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
12ba0 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
12bb0 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
12bc0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
12bd0 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
12be0 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
12bf0 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25   exactly like "%
12c00 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  s" with the.** a
12c10 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
12c20 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
12c30 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
12c40 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
12c50 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
12c60 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
12c70 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
12c80 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d  ut string. {END}
12c90 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
12ca0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30 33  S:.**.** {F17403
12cb0 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
12cc0 6d 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 20 5b  mprintf()] and [
12cd0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
12ce0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ()] interfaces.*
12cf0 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75  *           retu
12d00 72 6e 20 65 69 74 68 65 72 20 70 6f 69 6e 74 65  rn either pointe
12d10 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
12d20 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
12d30 6e 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 20  ngs held in.**  
12d40 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20           memory 
12d50 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
12d60 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
12d70 20 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   or NULL pointer
12d80 73 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  s if.**         
12d90 20 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c    a call to [sql
12da0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66  ite3_malloc()] f
12db0 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37  ails..**.** {F17
12dc0 34 30 36 7d 20 20 54 68 65 20 5b 73 71 6c 69 74  406}  The [sqlit
12dd0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
12de0 6e 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20  nterface writes 
12df0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
12e00 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 55  d.**           U
12e10 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 74 6f  TF-8 string into
12e20 20 74 68 65 20 62 75 66 66 65 72 20 70 6f 69 6e   the buffer poin
12e30 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 73 65  ted to by the se
12e40 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
12e50 2a 20 20 20 20 20 20 20 20 20 20 20 70 72 6f 76  *           prov
12e60 69 64 65 64 20 74 68 61 74 20 74 68 65 20 66 69  ided that the fi
12e70 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
12e80 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
12e90 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 34 30  ro..**.** {F1740
12ea0 37 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  7}  The [sqlite3
12eb0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74  _snprintf()] int
12ec0 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
12ed0 77 72 69 74 65 20 73 6c 6f 74 73 20 6f 66 0a 2a  write slots of.*
12ee0 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 73 20  *           its 
12ef0 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 28 74  output buffer (t
12f00 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
12f10 74 65 72 29 20 6f 75 74 73 69 64 65 20 74 68 65  ter) outside the
12f20 20 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20   range.**       
12f30 20 20 20 20 6f 66 20 30 20 74 68 72 6f 75 67 68      of 0 through
12f40 20 4e 2d 31 20 28 77 68 65 72 65 20 4e 20 69 73   N-1 (where N is
12f50 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
12f60 65 74 65 72 29 0a 2a 2a 20 20 20 20 20 20 20 20  eter).**        
12f70 20 20 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66     regardless of
12f80 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
12f90 68 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20  he string.**    
12fa0 20 20 20 20 20 20 20 72 65 71 75 65 73 74 65 64         requested
12fb0 20 62 79 20 74 68 65 20 66 6f 72 6d 61 74 20 73   by the format s
12fc0 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2f  pecification..*/
12fd0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d  .char *sqlite3_m
12fe0 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
12ff0 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73  r*,...);.char *s
13000 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
13010 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
13020 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c  list);.char *sql
13030 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e  ite3_snprintf(in
13040 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
13050 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  ar*, ...);../*.*
13060 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
13070 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75  ry Allocation Su
13080 62 73 79 73 74 65 6d 20 7b 46 31 37 33 30 30 7d  bsystem {F17300}
13090 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  .**.** The SQLit
130a0 65 20 63 6f 72 65 20 20 75 73 65 73 20 74 68 65  e core  uses the
130b0 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
130c0 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
130d0 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
130e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
130f0 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22  on needs. "Core"
13100 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
13110 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65   sentence.** doe
13120 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70  s not include op
13130 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
13140 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c  pecific VFS impl
13150 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
13160 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20  .** Windows VFS 
13170 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c  uses native mall
13180 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
13190 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
131a0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ons..**.** The s
131b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
131c0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
131d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62  a pointer to a b
131e0 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  lock.** of memor
131f0 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  y at least N byt
13200 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68  es in length, wh
13210 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72  ere N is the par
13220 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71  ameter..** If sq
13230 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
13240 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61  s unable to obta
13250 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72  in sufficient fr
13260 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74  ee.** memory, it
13270 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
13280 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 74 68 65  pointer.  If the
13290 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a   parameter N to.
132a0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
132b0 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e  c() is zero or n
132c0 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c  egative then sql
132d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65  ite3_malloc() re
132e0 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  turns.** a NULL 
132f0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43  pointer..**.** C
13300 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
13310 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
13320 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
13330 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
13340 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
13350 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
13360 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
13370 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
13380 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
13390 20 72 65 75 73 65 64 2e 20 20 54 68 65 20 73 71   reused.  The sq
133a0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
133b0 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
133c0 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
133d0 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
133e0 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
133f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
13400 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
13410 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
13420 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65  After being free
13430 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f  d, memory.** sho
13440 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72  uld neither be r
13450 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e  ead nor written.
13460 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70    Even reading p
13470 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a  reviously freed.
13480 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20  ** memory might 
13490 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
134a0 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
134b0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
134c0 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  rror..** Memory 
134d0 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
134e0 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
134f0 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
13500 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
13510 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
13520 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
13530 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
13540 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
13550 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
13560 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
13570 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
13580 6c 69 74 65 33 5f 66 72 65 65 28 29 2e 0a 2a 2a  lite3_free()..**
13590 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
135a0 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66  realloc() interf
135b0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
135c0 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
135d0 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
135e0 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61  ion to be at lea
135f0 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72  st N bytes, wher
13600 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65  e N is the.** se
13610 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
13620 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
13630 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73  cation to be res
13640 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73  ized is the firs
13650 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  t.** parameter. 
13660 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61   If the first pa
13670 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
13680 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
13690 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
136a0 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
136b0 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
136c0 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
136d0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
136e0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
136f0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
13700 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
13710 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65  loc()..** If the
13720 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
13730 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
13740 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
13750 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
13760 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
13770 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
13780 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
13790 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50  * sqlite3_free(P
137a0 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65  ) where P is the
137b0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
137c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
137d0 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65  loc()..** sqlite
137e0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
137f0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
13800 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
13810 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
13820 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
13830 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73  ize or NULL if s
13840 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
13850 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
13860 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20  .** If M is the 
13870 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
13880 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
13890 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
138a0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
138b0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
138c0 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
138d0 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
138e0 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
138f0 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
13900 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72  loc() and the pr
13910 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
13920 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73  s freed..** If s
13930 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
13940 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74   returns NULL, t
13950 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c  hen the prior al
13960 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e  location.** is n
13970 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
13980 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
13990 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
139a0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69  alloc() and sqli
139b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
139c0 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
139d0 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
139e0 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
139f0 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  y. {END}.**.** T
13a00 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65  he default imple
13a10 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
13a20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13a30 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75 73 65  on subsystem use
13a40 73 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28  s.** the malloc(
13a50 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ), realloc() and
13a60 20 66 72 65 65 28 29 20 70 72 6f 76 69 64 65 64   free() provided
13a70 20 62 79 20 74 68 65 20 73 74 61 6e 64 61 72 64   by the standard
13a80 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b   C library..** {
13a90 46 31 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c  F17382} However,
13aa0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
13ab0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
13ac0 2a 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59  ** SQLITE_MEMORY
13ad0 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e  _SIZE=<i>NNN</i>
13ae0 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
13af0 6d 61 63 72 6f 20 28 77 68 65 72 65 20 3c 69 3e  macro (where <i>
13b00 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e  NNN</i>.** is an
13b10 20 69 6e 74 65 67 65 72 29 2c 20 74 68 65 6e 20   integer), then 
13b20 53 51 4c 69 74 65 20 63 72 65 61 74 65 20 61 20  SQLite create a 
13b30 73 74 61 74 69 63 20 61 72 72 61 79 20 6f 66 20  static array of 
13b40 61 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e  at least.** <i>N
13b50 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20  NN</i> bytes in 
13b60 73 69 7a 65 20 61 6e 64 20 75 73 65 73 20 74 68  size and uses th
13b70 61 74 20 61 72 72 61 79 20 66 6f 72 20 61 6c 6c  at array for all
13b80 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 0a   of its dynamic.
13b90 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
13ba0 74 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44  tion needs. {END
13bb0 7d 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65  }  Additional me
13bc0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f  mory allocator o
13bd0 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65  ptions.** may be
13be0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
13bf0 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a   releases..**.**
13c00 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
13c10 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
13c20 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
13c30 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
13c40 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
13c50 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
13c60 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
13c70 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
13c80 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
13c90 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
13ca0 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
13cb0 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
13cc0 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
13cd0 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
13ce0 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
13cf0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
13d00 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
13d10 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20  .** The Windows 
13d20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
13d30 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20  er calls.** the 
13d40 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
13d50 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
13d60 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
13d70 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
13d80 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
13d90 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
13da0 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
13db0 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
13dc0 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
13dd0 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
13de0 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
13df0 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
13e00 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
13e10 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65  on errors are de
13e20 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74  tected, but.** t
13e30 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64  hey are reported
13e40 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45   back as [SQLITE
13e50 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a  _CANTOPEN] or.**
13e60 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20   [SQLITE_IOERR] 
13e70 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c  rather than [SQL
13e80 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
13e90 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
13ea0 0a 2a 2a 20 7b 46 31 37 33 30 33 7d 20 20 54 68  .** {F17303}  Th
13eb0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
13ec0 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  c(N)] interface 
13ed0 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 20 61  returns either a
13ee0 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20   pointer to.**  
13ef0 20 20 20 20 20 20 20 20 20 61 20 6e 65 77 6c 79           a newly
13f00 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 62 6c 6f   checked-out blo
13f10 63 6b 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ck of at least N
13f20 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
13f30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
13f40 61 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69  at is 8-byte ali
13f50 67 6e 65 64 2c 20 6f 72 20 69 74 20 72 65 74 75  gned, or it retu
13f60 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 74 20 69  rns NULL if it i
13f70 73 20 75 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20  s unable.**     
13f80 20 20 20 20 20 20 74 6f 20 66 75 6c 66 69 6c 6c        to fulfill
13f90 20 74 68 65 20 72 65 71 75 65 73 74 2e 0a 2a 2a   the request..**
13fa0 0a 2a 2a 20 7b 46 31 37 33 30 34 7d 20 20 54 68  .** {F17304}  Th
13fb0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
13fc0 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  c(N)] interface 
13fd0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
13fe0 6f 69 6e 74 65 72 20 69 66 0a 2a 2a 20 20 20 20  ointer if.**    
13ff0 20 20 20 20 20 20 20 4e 20 69 73 20 6c 65 73 73         N is less
14000 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
14010 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 46  o zero..**.** {F
14020 31 37 33 30 35 7d 20 20 54 68 65 20 5b 73 71 6c  17305}  The [sql
14030 69 74 65 33 5f 66 72 65 65 28 50 29 5d 20 69 6e  ite3_free(P)] in
14040 74 65 72 66 61 63 65 20 72 65 6c 65 61 73 65 73  terface releases
14050 20 6d 65 6d 6f 72 79 20 70 72 65 76 69 6f 75 73   memory previous
14060 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ly.**           
14070 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
14080 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
14090 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
140a0 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  lloc()],.**     
140b0 20 20 20 20 20 20 6d 61 6b 69 6e 67 20 69 74 20        making it 
140c0 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 72 65  available for re
140d0 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  use..**.** {F173
140e0 30 36 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b  06}  A call to [
140f0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 4e 55 4c  sqlite3_free(NUL
14100 4c 29 5d 20 69 73 20 61 20 68 61 72 6d 6c 65 73  L)] is a harmles
14110 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b  s no-op..**.** {
14120 46 31 37 33 31 30 7d 20 20 41 20 63 61 6c 6c 20  F17310}  A call 
14130 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  to [sqlite3_real
14140 6c 6f 63 28 30 2c 4e 29 5d 20 69 73 20 65 71 75  loc(0,N)] is equ
14150 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c  ivalent to a cal
14160 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  l.**           t
14170 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
14180 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  c(N)]..**.** {F1
14190 37 33 31 32 7d 20 20 41 20 63 61 6c 6c 20 74 6f  7312}  A call to
141a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
141b0 63 28 50 2c 30 29 5d 20 69 73 20 65 71 75 69 76  c(P,0)] is equiv
141c0 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a  alent to a call.
141d0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20  **           to 
141e0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29  [sqlite3_free(P)
141f0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 31 35  ]..**.** {F17315
14200 7d 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  }  The SQLite co
14210 72 65 20 75 73 65 73 20 5b 73 71 6c 69 74 65 33  re uses [sqlite3
14220 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
14230 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c  ite3_realloc()],
14240 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 6e  .**           an
14250 64 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  d [sqlite3_free(
14260 29 5d 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  )] for all of it
14270 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
14280 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ion and.**      
14290 20 20 20 20 20 64 65 61 6c 6c 6f 63 61 74 69 6f       deallocatio
142a0 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b  n needs..**.** {
142b0 46 31 37 33 31 38 7d 20 20 54 68 65 20 5b 73 71  F17318}  The [sq
142c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c  lite3_realloc(P,
142d0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
142e0 74 75 72 6e 73 20 65 69 74 68 65 72 20 61 20 70  turns either a p
142f0 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ointer.**       
14300 20 20 20 20 74 6f 20 61 20 62 6c 6f 63 6b 20 6f      to a block o
14310 66 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 6d 65  f checked-out me
14320 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74  mory of at least
14330 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
14340 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
14350 61 74 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69  at is 8-byte ali
14360 67 6e 65 64 2c 20 6f 72 20 61 20 4e 55 4c 4c 20  gned, or a NULL 
14370 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  pointer..**.** {
14380 46 31 37 33 32 31 7d 20 20 57 68 65 6e 20 5b 73  F17321}  When [s
14390 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50  qlite3_realloc(P
143a0 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e  ,N)] returns a n
143b0 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
143c0 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20   it first.**    
143d0 20 20 20 20 20 20 20 63 6f 70 69 65 73 20 74 68         copies th
143e0 65 20 66 69 72 73 74 20 4b 20 62 79 74 65 73 20  e first K bytes 
143f0 6f 66 20 63 6f 6e 74 65 6e 74 20 66 72 6f 6d 20  of content from 
14400 50 20 69 6e 74 6f 20 74 68 65 20 6e 65 77 6c 79  P into the newly
14410 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 6c  .**           al
14420 6c 6f 63 61 74 65 64 20 62 6c 6f 63 6b 2c 20 77  located block, w
14430 68 65 72 65 20 4b 20 69 73 20 74 68 65 20 6c 65  here K is the le
14440 73 73 65 72 20 6f 66 20 4e 20 61 6e 64 20 74 68  sser of N and th
14450 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 20 20 20  e size of.**    
14460 20 20 20 20 20 20 20 74 68 65 20 62 75 66 66 65         the buffe
14470 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33  r P..**.** {F173
14480 32 32 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74  22}  When [sqlit
14490 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d  e3_realloc(P,N)]
144a0 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e   returns a non-N
144b0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20  ULL pointer, it 
144c0 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20  first.**        
144d0 20 20 20 72 65 6c 65 61 73 65 73 20 74 68 65 20     releases the 
144e0 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20  buffer P..**.** 
144f0 7b 46 31 37 33 32 33 7d 20 20 57 68 65 6e 20 5b  {F17323}  When [
14500 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
14510 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 4e 55  P,N)] returns NU
14520 4c 4c 2c 20 74 68 65 20 62 75 66 66 65 72 20 50  LL, the buffer P
14530 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
14540 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 20 6f 72   not modified or
14550 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
14560 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a   LIMITATIONS:.**
14570 0a 2a 2a 20 7b 55 31 37 33 35 30 7d 20 20 54 68  .** {U17350}  Th
14580 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
14590 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
145a0 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
145b0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
145c0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d 75 73  **           mus
145d0 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c  t be either NULL
145e0 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72   or else pointer
145f0 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
14600 61 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20  a prior.**      
14610 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 20       invocation 
14620 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
14630 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
14640 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61  3_realloc()] tha
14650 74 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20  t have.**       
14660 20 20 20 20 6e 6f 74 20 79 65 74 20 62 65 65 6e      not yet been
14670 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
14680 20 7b 55 31 37 33 35 31 7d 20 20 54 68 65 20 61   {U17351}  The a
14690 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
146a0 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
146b0 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
146c0 20 20 20 20 20 20 20 20 20 20 20 61 20 62 6c 6f             a blo
146d0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
146e0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
146f0 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
14700 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
14710 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b  te3_free()] or [
14720 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
14730 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  )]..*/.void *sql
14740 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
14750 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
14760 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69  realloc(void*, i
14770 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
14780 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a  3_free(void*);..
14790 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
147a0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
147b0 20 53 74 61 74 69 73 74 69 63 73 20 7b 46 31 37   Statistics {F17
147c0 33 37 30 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  370}.**.** SQLit
147d0 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65  e provides these
147e0 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20   two interfaces 
147f0 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e  for reporting on
14800 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f   the status.** o
14810 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
14820 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
14830 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
14840 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
14850 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c  ()].** routines,
14860 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20   which form the 
14870 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
14880 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
14890 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  stem..**.** INVA
148a0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46  RIANTS:.**.** {F
148b0 31 37 33 37 31 7d 20 54 68 65 20 5b 73 71 6c 69  17371} The [sqli
148c0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
148d0 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
148e0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
148f0 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20   bytes.**       
14900 20 20 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72     of memory cur
14910 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
14920 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
14930 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 0a   not freed)..**.
14940 2a 2a 20 7b 46 31 37 33 37 33 7d 20 54 68 65 20  ** {F17373} The 
14950 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
14960 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75  highwater()] rou
14970 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
14980 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 20 20 20 20   maximum.**     
14990 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 5b 73       value of [s
149a0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
149b0 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
149c0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
149d0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 61 73 20  **          was 
149e0 6c 61 73 74 20 72 65 73 65 74 2e 0a 2a 2a 0a 2a  last reset..**.*
149f0 2a 20 7b 46 31 37 33 37 34 7d 20 54 68 65 20 76  * {F17374} The v
14a00 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
14a10 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
14a20 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  y_used()] and.**
14a30 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
14a40 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
14a50 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
14a60 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 20  ny overhead.**  
14a70 20 20 20 20 20 20 20 20 61 64 64 65 64 20 62 79          added by
14a80 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
14a90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
14aa0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
14ab0 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
14ac0 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
14ad0 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
14ae0 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
14af0 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
14b00 20 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65           routine
14b10 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
14b20 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
14b30 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 37 33 37  ll..**.** {F1737
14b40 35 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  5} The memory hi
14b50 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
14b60 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
14b70 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
14b80 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
14b90 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
14ba0 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
14bb0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
14bc0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
14bd0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
14be0 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74  ighwater()] is t
14bf0 72 75 65 2e 20 20 54 68 65 20 76 61 6c 75 65 20  rue.  The value 
14c00 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20  returned.**     
14c10 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33       by [sqlite3
14c20 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
14c30 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
14c40 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
14c50 20 20 20 20 20 20 20 20 20 70 72 69 6f 72 20 74           prior t
14c60 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a  o the reset..*/.
14c70 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
14c80 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
14c90 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33  d(void);.sqlite3
14ca0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
14cb0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
14cc0 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a  int resetFlag);.
14cd0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
14ce0 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e   Pseudo-Random N
14cf0 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 20  umber Generator 
14d00 7b 46 31 37 33 39 30 7d 0a 2a 2a 0a 2a 2a 20 53  {F17390}.**.** S
14d10 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61  QLite contains a
14d20 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73   high-quality ps
14d30 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62  eudo-random numb
14d40 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52  er generator (PR
14d50 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73  NG) used to.** s
14d60 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 52 4f 57  elect random ROW
14d70 49 44 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69  IDs when inserti
14d80 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
14d90 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
14da0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
14db0 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
14dc0 73 69 62 6c 65 20 52 4f 57 49 44 2e 20 20 54 68  sible ROWID.  Th
14dd0 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
14de0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
14df0 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
14e00 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
14e10 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
14e20 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
14e30 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
14e40 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
14e50 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
14e60 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
14e70 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  es..**.** A call
14e80 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
14e90 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
14ea0 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
14eb0 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a  to buffer P..**.
14ec0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69 6d  ** The first tim
14ed0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
14ee0 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65  s invoked (eithe
14ef0 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20  r internally or 
14f00 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  by.** the applic
14f10 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20  ation) the PRNG 
14f20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  is seeded using 
14f30 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
14f40 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ned.** from the 
14f50 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68  xRandomness meth
14f60 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
14f70 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
14f80 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c  object..** On al
14f90 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  l subsequent inv
14fa0 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73  ocations, the ps
14fb0 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20  eudo-randomness 
14fc0 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20  is generated.** 
14fd0 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77  internally and w
14fe0 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20  ithout recourse 
14ff0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
15000 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73  vfs] xRandomness
15010 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a  .** method..**.*
15020 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
15030 0a 2a 2a 20 7b 46 31 37 33 39 32 7d 20 54 68 65  .** {F17392} The
15040 20 5b 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d   [sqlite3_random
15050 6e 65 73 73 28 4e 2c 50 29 5d 20 69 6e 74 65 72  ness(N,P)] inter
15060 66 61 63 65 20 77 72 69 74 65 73 20 4e 20 62 79  face writes N by
15070 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  tes of.**       
15080 20 20 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20     high-quality 
15090 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
150a0 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e  s into buffer P.
150b0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
150c0 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
150d0 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
150e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
150f0 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
15100 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
15110 6b 73 20 7b 46 31 32 35 30 30 7d 0a 2a 2a 0a 2a  ks {F12500}.**.*
15120 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
15130 65 67 69 73 74 65 72 73 20 61 20 61 75 74 68 6f  egisters a autho
15140 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
15150 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
15160 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
15170 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
15180 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
15190 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
151a0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
151b0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
151c0 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
151d0 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
151e0 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
151f0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
15200 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
15210 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
15220 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
15230 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
15240 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
15250 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
15260 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
15270 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
15280 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
15290 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
152a0 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
152b0 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
152c0 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
152d0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
152e0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
152f0 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
15300 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
15310 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61 75  allowed.  The au
15320 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
15330 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
15340 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
15350 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
15360 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
15370 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
15380 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
15390 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
153a0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
153b0 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
153c0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
153d0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
153e0 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
153f0 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
15400 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
15410 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
15420 72 72 6f 72 2e 20 20 49 66 20 74 68 65 20 61 75  rror.  If the au
15430 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
15440 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
15450 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
15460 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
15470 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
15480 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
15490 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
154a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
154b0 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
154c0 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
154d0 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
154e0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
154f0 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
15500 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
15510 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
15520 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
15530 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
15540 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
15550 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
15560 6b 2e 20 20 57 68 65 6e 20 74 68 65 20 63 61 6c  k.  When the cal
15570 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
15580 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
15590 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
155a0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
155b0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
155c0 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
155d0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
155e0 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
155f0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
15600 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
15610 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
15620 65 64 2e 20 20 49 66 20 74 68 65 20 61 75 74 68  ed.  If the auth
15630 6f 72 69 7a 65 72 20 63 6f 64 65 20 69 73 20 5b  orizer code is [
15640 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
15650 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
15660 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
15670 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
15680 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
15690 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
156a0 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
156b0 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
156c0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
156d0 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
156e0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
156f0 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
15700 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
15710 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
15720 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
15730 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
15740 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
15750 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
15760 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
15770 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
15780 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
15790 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
157a0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
157b0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
157c0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
157d0 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
157e0 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
157f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
15800 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
15810 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
15820 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  . The second par
15830 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
15840 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
15850 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f  integer [SQLITE_
15860 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f  COPY | action co
15870 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
15880 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63  es.** the partic
15890 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62  ular action to b
158a0 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 54 68  e authorized. Th
158b0 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
158c0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
158d0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
158e0 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
158f0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
15900 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
15910 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
15920 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
15930 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
15940 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  ized..**.** An a
15950 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65  uthorizer is use
15960 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
15970 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
15980 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ing].** SQL stat
15990 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75  ements from an u
159a0 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c  ntrusted source,
159b0 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20   to ensure that 
159c0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
159d0 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79  ts.** do not try
159e0 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20   to access data 
159f0 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c  they are not all
15a00 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20  owed to see, or 
15a10 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
15a20 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75  .** try to execu
15a30 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61  te malicious sta
15a40 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d  tements that dam
15a50 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  age the database
15a60 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
15a70 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
15a80 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73  n may allow a us
15a90 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69  er to enter arbi
15aa0 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65  trary.** SQL que
15ab0 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74  ries for evaluat
15ac0 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73  ion by a databas
15ad0 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c  e.  But the appl
15ae0 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20  ication does.** 
15af0 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65  not want the use
15b00 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20  r to be able to 
15b10 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63  make arbitrary c
15b20 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a  hanges to the.**
15b30 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61   database.  An a
15b40 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20  uthorizer could 
15b50 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70  then be put in p
15b60 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a  lace while the.*
15b70 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  * user-entered S
15b80 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c  QL is being [sql
15b90 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
15ba0 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a  repared] that.**
15bb0 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79   disallows every
15bc0 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45  thing except [SE
15bd0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73  LECT] statements
15be0 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ..**.** Applicat
15bf0 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74  ions that need t
15c00 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72  o process SQL fr
15c10 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  om untrusted sou
15c20 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c  rces.** might al
15c30 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65  so consider lowe
15c40 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69  ring resource li
15c50 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69  mits using [sqli
15c60 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
15c70 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74  and limiting dat
15c80 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67  abase size using
15c90 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63   the [max_page_c
15ca0 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a  ount] [PRAGMA].*
15cb0 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  * in addition to
15cc0 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72   using an author
15cd0 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79  izer..**.** Only
15ce0 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
15cf0 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
15d00 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
15d10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
15d20 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
15d30 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
15d40 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
15d50 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
15d60 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
15d70 20 20 44 69 73 61 62 6c 65 20 74 68 65 20 61 75    Disable the au
15d80 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
15d90 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
15da0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
15db0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
15dc0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
15dd0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
15de0 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
15df0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
15e00 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
15e10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
15e20 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
15e30 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
15e40 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
15e50 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
15e60 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
15e70 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
15e80 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
15e90 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
15ea0 2a 0a 2a 2a 20 7b 46 31 32 35 30 31 7d 20 54 68  *.** {F12501} Th
15eb0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
15ec0 75 74 68 6f 72 69 7a 65 72 28 44 2c 2e 2e 2e 29  uthorizer(D,...)
15ed0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
15ee0 73 74 65 72 73 20 61 0a 2a 2a 20 20 20 20 20 20  sters a.**      
15ef0 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72 20 63      authorizer c
15f00 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 64 61 74  allback with dat
15f10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15f20 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 30   D..**.** {F1250
15f30 32 7d 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  2} The authorize
15f40 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
15f50 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
15f60 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 20  tements are.**  
15f70 20 20 20 20 20 20 20 20 62 65 69 6e 67 20 63 6f          being co
15f80 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  mpiled..**.** {F
15f90 31 32 35 30 33 7d 20 49 66 20 74 68 65 20 61 75  12503} If the au
15fa0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
15fb0 6b 20 72 65 74 75 72 6e 73 20 61 6e 79 20 76 61  k returns any va
15fc0 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a  lue other than.*
15fd0 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
15fe0 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
15ff0 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
16000 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 6e 0a  ITE_DENY], then.
16010 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
16020 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
16030 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
16040 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 63  lent call that c
16050 61 75 73 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  aused.**        
16060 20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72    the authorizer
16070 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e   callback to run
16080 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68   shall fail with
16090 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
160a0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65  [SQLITE_ERROR] e
160b0 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e  rror code and an
160c0 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72   appropriate err
160d0 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
160e0 2a 20 7b 46 31 32 35 30 34 7d 20 57 68 65 6e 20  * {F12504} When 
160f0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
16100 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
16110 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65  [SQLITE_OK], the
16120 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 20   operation.**   
16130 20 20 20 20 20 20 20 64 65 73 63 72 69 62 65 64         described
16140 20 69 73 20 70 72 6f 63 65 73 73 65 64 20 6e 6f   is processed no
16150 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46  rmally..**.** {F
16160 31 32 35 30 35 7d 20 57 68 65 6e 20 74 68 65 20  12505} When the 
16170 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
16180 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
16190 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
161a0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
161b0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
161c0 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
161d0 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64  call that caused
161e0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
161f0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
16200 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c  back to run shal
16210 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20  l fail.**       
16220 20 20 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49     with an [SQLI
16230 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20  TE_ERROR] error 
16240 63 6f 64 65 20 61 6e 64 20 61 6e 20 65 72 72 6f  code and an erro
16250 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20  r message.**    
16260 20 20 20 20 20 20 65 78 70 6c 61 69 6e 69 6e 67        explaining
16270 20 74 68 61 74 20 61 63 63 65 73 73 20 69 73 20   that access is 
16280 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46  denied..**.** {F
16290 31 32 35 30 36 7d 20 49 66 20 74 68 65 20 61 75  12506} If the au
162a0 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74  thorizer code (t
162b0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
162c0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
162d0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  er.**          c
162e0 61 6c 6c 62 61 63 6b 29 20 69 73 20 5b 53 51 4c  allback) is [SQL
162f0 49 54 45 5f 52 45 41 44 5d 20 61 6e 64 20 74 68  ITE_READ] and th
16300 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
16310 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
16320 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
16330 45 5f 49 47 4e 4f 52 45 5d 2c 20 74 68 65 6e 20  E_IGNORE], then 
16340 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
16350 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
16360 75 63 74 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  ucted to.**     
16370 20 20 20 20 20 69 6e 73 65 72 74 20 61 20 4e 55       insert a NU
16380 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
16390 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
163a0 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
163b0 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20   have.**        
163c0 20 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b    been read if [
163d0 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
163e0 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  een returned..**
163f0 0a 2a 2a 20 7b 46 31 32 35 30 37 7d 20 49 66 20  .** {F12507} If 
16400 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
16410 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72  ode (the 2nd par
16420 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
16430 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20  thorizer.**     
16440 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69       callback) i
16450 73 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72  s anything other
16460 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45   than [SQLITE_RE
16470 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  AD], then.**    
16480 20 20 20 20 20 20 61 20 72 65 74 75 72 6e 20 6f        a return o
16490 66 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  f [SQLITE_IGNORE
164a0 5d 20 68 61 73 20 74 68 65 20 73 61 6d 65 20 65  ] has the same e
164b0 66 66 65 63 74 20 61 73 20 5b 53 51 4c 49 54 45  ffect as [SQLITE
164c0 5f 44 45 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  _DENY]..**.** {F
164d0 31 32 35 31 30 7d 20 54 68 65 20 66 69 72 73 74  12510} The first
164e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
164f0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
16500 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
16510 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
16520 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
16530 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
16540 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
16550 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  r()] interface..
16560 2a 2a 0a 2a 2a 20 7b 46 31 32 35 31 31 7d 20 54  **.** {F12511} T
16570 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
16580 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
16590 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
165a0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  r.**          [S
165b0 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
165c0 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
165d0 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61 72  pecifies the par
165e0 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a  ticular action.*
165f0 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 62 65  *          to be
16600 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
16610 2a 2a 20 7b 46 31 32 35 31 32 7d 20 54 68 65 20  ** {F12512} The 
16620 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
16630 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  xth parameters t
16640 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
16650 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  re.**          z
16660 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
16670 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
16680 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ain.**          
16690 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69  additional detai
166a0 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
166b0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
166c0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  ized..**.** {F12
166d0 35 32 30 7d 20 45 61 63 68 20 63 61 6c 6c 20 74  520} Each call t
166e0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  o [sqlite3_set_a
166f0 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 6f 76 65  uthorizer()] ove
16700 72 72 69 64 65 73 0a 2a 2a 20 20 20 20 20 20 20  rrides.**       
16710 20 20 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c     any previousl
16720 79 20 69 6e 73 74 61 6c 6c 65 64 20 61 75 74 68  y installed auth
16730 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46  orizer..**.** {F
16740 31 32 35 32 31 7d 20 41 20 4e 55 4c 4c 20 61 75  12521} A NULL au
16750 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20 74  thorizer means t
16760 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61  hat no authoriza
16770 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
16780 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
16790 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  oked..**.** {F12
167a0 35 32 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74  522} The default
167b0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e   authorizer is N
167c0 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
167d0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
167e0 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
167f0 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
16800 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
16810 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
16820 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
16830 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
16840 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
16850 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16860 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
16870 72 6e 20 43 6f 64 65 73 20 7b 46 31 32 35 39 30  rn Codes {F12590
16880 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  }.**.** The [sql
16890 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
168a0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
168b0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
168c0 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
168d0 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
168e0 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
168f0 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
16900 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
16910 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
16920 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
16930 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
16940 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
16950 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
16960 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
16970 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
16980 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
16990 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
169a0 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69  mation..*/.#defi
169b0 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20  ne SQLITE_DENY  
169c0 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68   1   /* Abort th
169d0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
169e0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f  with an error */
169f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16a00 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f  IGNORE 2   /* Do
16a10 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73  n't allow access
16a20 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65  , but don't gene
16a30 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f  rate an error */
16a40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16a50 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74  : Authorizer Act
16a60 69 6f 6e 20 43 6f 64 65 73 20 7b 46 31 32 35 35  ion Codes {F1255
16a70 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  0}.**.** The [sq
16a80 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
16a90 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
16aa0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
16ab0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
16ac0 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
16ad0 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
16ae0 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
16af0 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
16b00 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
16b10 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
16b20 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
16b30 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
16b40 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
16b50 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
16b60 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
16b70 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
16b80 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
16b90 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
16ba0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
16bb0 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
16bc0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
16bd0 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
16be0 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
16bf0 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
16c00 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
16c10 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
16c20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
16c30 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
16c40 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
16c50 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
16c60 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
16c70 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
16c80 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
16c90 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
16ca0 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
16cb0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
16cc0 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
16cd0 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
16ce0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
16cf0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
16d00 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
16d10 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
16d20 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
16d30 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 61 72  le.  The 6th par
16d40 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
16d50 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
16d60 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
16d70 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
16d80 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
16d90 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
16da0 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
16db0 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
16dc0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
16dd0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
16de0 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
16df0 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
16e00 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e  L code..**.** IN
16e10 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
16e20 7b 46 31 32 35 35 31 7d 20 54 68 65 20 73 65 63  {F12551} The sec
16e30 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
16e40 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
16e50 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
16e60 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
16e70 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69  izer callback] i
16e80 73 20 61 6c 77 61 79 73 20 61 6e 20 69 6e 74 65  s always an inte
16e90 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ger.**          
16ea0 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
16eb0 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20  uthorizer code] 
16ec0 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 77  that specifies w
16ed0 68 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20  hat action.**   
16ee0 20 20 20 20 20 20 20 69 73 20 62 65 69 6e 67 20         is being 
16ef0 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
16f00 2a 20 7b 46 31 32 35 35 32 7d 20 54 68 65 20 33  * {F12552} The 3
16f10 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
16f20 65 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20  eters to the.** 
16f30 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
16f40 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
16f50 20 7c 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e   | authorization
16f60 20 63 61 6c 6c 62 61 63 6b 5d 0a 2a 2a 20 20 20   callback].**   
16f70 20 20 20 20 20 20 20 77 69 6c 6c 20 62 65 20 70         will be p
16f80 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
16f90 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
16fa0 68 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  hich.**         
16fb0 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
16fc0 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d  authorizer code]
16fd0 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
16fe0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16ff0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 35 35 33 7d  ..**.** {F12553}
17000 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   The 5th paramet
17010 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  er to the.**    
17020 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
17030 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
17040 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
17050 61 63 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d 65  ack] is the name
17060 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
17070 74 68 65 20 64 61 74 61 62 61 73 65 20 28 65 78  the database (ex
17080 61 6d 70 6c 65 3a 20 22 6d 61 69 6e 22 2c 20 22  ample: "main", "
17090 74 65 6d 70 22 2c 20 65 74 63 2e 29 20 69 66 20  temp", etc.) if 
170a0 61 70 70 6c 69 63 61 62 6c 65 2e 0a 2a 2a 0a 2a  applicable..**.*
170b0 2a 20 7b 46 31 32 35 35 34 7d 20 54 68 65 20 36  * {F12554} The 6
170c0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
170d0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
170e0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
170f0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
17100 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69  izer callback] i
17110 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20  s the name.**   
17120 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 69 6e         of the in
17130 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
17140 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
17150 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
17160 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
17170 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
17180 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
17190 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
171a0 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
171b0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 70 2d  **          top-
171c0 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
171d0 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
171e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
171f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
17200 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
17210 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
17220 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17230 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
17240 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
17250 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
17260 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
17270 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17280 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
17290 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
172a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
172b0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
172c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
172d0 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
172e0 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
172f0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
17300 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
17310 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
17320 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
17330 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
17340 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
17350 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
17360 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
17370 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
17380 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
17390 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
173a0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
173b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
173c0 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
173d0 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
173e0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
173f0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
17400 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
17410 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
17420 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
17430 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
17440 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
17450 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
17460 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
17470 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
17480 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
17490 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
174a0 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
174b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
174c0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
174d0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
174e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
174f0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
17500 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
17510 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
17520 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
17530 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
17540 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
17550 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
17560 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
17570 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
17580 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
17590 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
175a0 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
175b0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
175c0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
175d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
175e0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
175f0 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
17600 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
17610 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
17620 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17630 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
17640 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
17650 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
17660 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
17670 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17680 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
17690 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
176a0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
176b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
176c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
176d0 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
176e0 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
176f0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
17700 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
17710 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17720 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
17730 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
17740 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
17750 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
17760 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17770 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
17780 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
17790 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
177a0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
177b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
177c0 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
177d0 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
177e0 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
177f0 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
17800 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
17810 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
17820 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
17830 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
17840 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
17850 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
17860 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
17870 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
17880 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
17890 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
178a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
178b0 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
178c0 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   22   /* NULL   
178d0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
178e0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
178f0 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
17900 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
17910 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
17920 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
17930 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
17940 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
17950 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
17960 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
17970 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
17980 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
17990 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
179a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
179b0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
179c0 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
179d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
179e0 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
179f0 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
17a00 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
17a10 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
17a20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
17a30 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
17a40 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
17a50 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
17a60 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
17a70 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
17a80 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
17a90 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
17aa0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
17ab0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
17ac0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17ad0 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
17ae0 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
17af0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
17b00 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
17b10 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17b20 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
17b30 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
17b40 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
17b50 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
17b60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17b70 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
17b80 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
17b90 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
17ba0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
17bb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17bc0 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20  E_COPY          
17bd0 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e          0   /* N
17be0 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f  o longer used */
17bf0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
17c00 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72  : Tracing And Pr
17c10 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e  ofiling Function
17c20 73 20 7b 46 31 32 32 38 30 7d 0a 2a 2a 0a 2a 2a  s {F12280}.**.**
17c30 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
17c40 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
17c50 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
17c60 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
17c70 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
17c80 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
17c90 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
17ca0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
17cb0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
17cc0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
17cd0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
17ce0 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
17cf0 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
17d00 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
17d10 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
17d20 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
17d30 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54  e3_step()]..** T
17d40 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
17d50 72 6e 73 20 61 20 55 54 46 2d 38 20 72 65 6e 64  rns a UTF-8 rend
17d60 65 72 69 6e 67 20 6f 66 20 74 68 65 20 53 51 4c  ering of the SQL
17d70 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 0a   statement text.
17d80 2a 2a 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  ** as the statem
17d90 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
17da0 20 65 78 65 63 75 74 69 6e 67 2e 20 20 41 64 64   executing.  Add
17db0 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b  itional callback
17dc0 73 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  s occur.** as ea
17dd0 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
17de0 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
17df0 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
17e00 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
17e10 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
17e20 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
17e30 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
17e40 68 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a  he trigger..**.*
17e50 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
17e60 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
17e70 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
17e80 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
17e90 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
17ea0 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
17eb0 73 68 65 73 2e 20 20 54 68 65 20 70 72 6f 66 69  shes.  The profi
17ec0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
17ed0 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
17ee0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
17ef0 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
17f00 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
17f10 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
17f20 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
17f30 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
17f40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
17f50 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 41 50  te3_profile() AP
17f60 49 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63  I is currently c
17f70 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69  onsidered experi
17f80 6d 65 6e 74 61 6c 20 61 6e 64 0a 2a 2a 20 69 73  mental and.** is
17f90 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
17fa0 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 69 6e  ge or removal in
17fb0 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
17fc0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 72 69  e..**.** The tri
17fd0 67 67 65 72 20 72 65 70 6f 72 74 69 6e 67 20 66  gger reporting f
17fe0 65 61 74 75 72 65 20 6f 66 20 74 68 65 20 74 72  eature of the tr
17ff0 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ace callback is 
18000 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 65 78  considered.** ex
18010 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
18020 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  s subject to cha
18030 6e 67 65 20 6f 72 20 72 65 6d 6f 76 61 6c 20 69  nge or removal i
18040 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
18050 73 2e 0a 2a 2a 20 46 75 74 75 72 65 20 76 65 72  s..** Future ver
18060 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
18070 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6e  might also add n
18080 65 77 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ew trace callbac
18090 6b 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  k.** invocations
180a0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
180b0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38  TS:.**.** {F1228
180c0 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  1} The callback 
180d0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
180e0 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  red by [sqlite3_
180f0 74 72 61 63 65 28 29 5d 20 69 73 0a 2a 2a 20 20  trace()] is.**  
18100 20 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 72          whenever
18110 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
18120 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 74  t first begins t
18130 6f 20 65 78 65 63 75 74 65 20 61 6e 64 0a 2a 2a  o execute and.**
18140 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 65 76            whenev
18150 65 72 20 61 20 74 72 69 67 67 65 72 20 73 75 62  er a trigger sub
18160 70 72 6f 67 72 61 6d 20 66 69 72 73 74 20 62 65  program first be
18170 67 69 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a  gins to run..**.
18180 2a 2a 20 7b 46 31 32 32 38 32 7d 20 45 61 63 68  ** {F12282} Each
18190 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
181a0 33 5f 74 72 61 63 65 28 29 5d 20 6f 76 65 72 72  3_trace()] overr
181b0 69 64 65 73 20 74 68 65 20 70 72 65 76 69 6f 75  ides the previou
181c0 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  sly.**          
181d0 72 65 67 69 73 74 65 72 65 64 20 74 72 61 63 65  registered trace
181e0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
181f0 20 7b 46 31 32 32 38 33 7d 20 41 20 4e 55 4c 4c   {F12283} A NULL
18200 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
18210 64 69 73 61 62 6c 65 73 20 74 72 61 63 69 6e 67  disables tracing
18220 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 34 7d  ..**.** {F12284}
18230 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
18240 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65  ent to the trace
18250 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
18260 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  opy of.**       
18270 20 20 20 74 68 65 20 70 6f 69 6e 74 65 72 20 77     the pointer w
18280 68 69 63 68 20 77 61 73 20 74 68 65 20 33 72 64  hich was the 3rd
18290 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
182a0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 2e 0a  lite3_trace()]..
182b0 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 35 7d 20 54  **.** {F12285} T
182c0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
182d0 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20  nt to the trace 
182e0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a  callback is a.**
182f0 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74            zero-t
18300 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
18310 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
18320 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 74  g the original t
18330 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ext.**          
18340 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  of the SQL state
18350 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 70  ment as it was p
18360 61 73 73 65 64 20 69 6e 74 6f 20 5b 73 71 6c 69  assed into [sqli
18370 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
18380 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
18390 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2c   the equivalent,
183a0 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65   or an SQL comme
183b0 6e 74 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  nt indicating th
183c0 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20  e beginning.**  
183d0 20 20 20 20 20 20 20 20 6f 66 20 61 20 74 72 69          of a tri
183e0 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e  gger subprogram.
183f0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32 38 37 7d 20  .**.** {F12287} 
18400 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
18410 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
18420 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f   by [sqlite3_pro
18430 66 69 6c 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b  file()] is invok
18440 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ed.**          a
18450 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
18460 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a  ment finishes..*
18470 2a 0a 2a 2a 20 7b 46 31 32 32 38 38 7d 20 54 68  *.** {F12288} Th
18480 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
18490 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65  r to the profile
184a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
184b0 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  opy of.**       
184c0 20 20 20 74 68 65 20 33 72 64 20 70 61 72 61 6d     the 3rd param
184d0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
184e0 5f 70 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a  _profile()]..**.
184f0 2a 2a 20 7b 46 31 32 32 38 39 7d 20 54 68 65 20  ** {F12289} The 
18500 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18510 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20   to the profile 
18520 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a  callback is a.**
18530 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74            zero-t
18540 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
18550 73 74 72 69 6e 67 20 74 68 61 74 20 63 6f 6e 74  string that cont
18560 61 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c 65 74  ains the complet
18570 65 20 74 65 78 74 20 6f 66 0a 2a 2a 20 20 20 20  e text of.**    
18580 20 20 20 20 20 20 74 68 65 20 53 51 4c 20 73 74        the SQL st
18590 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61  atement as it wa
185a0 73 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 5b  s processed by [
185b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
185c0 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  v2()].**        
185d0 20 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c    or the equival
185e0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 32  ent..**.** {F122
185f0 39 30 7d 20 54 68 65 20 74 68 69 72 64 20 70 61  90} The third pa
18600 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70  rameter to the p
18610 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
18620 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 0a 2a  is an estimate.*
18630 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
18640 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f  e number of nano
18650 73 65 63 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d  seconds of wall-
18660 63 6c 6f 63 6b 20 74 69 6d 65 20 72 65 71 75 69  clock time requi
18670 72 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  red to.**       
18680 20 20 20 72 75 6e 20 74 68 65 20 53 51 4c 20 73     run the SQL s
18690 74 61 74 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74  tatement from st
186a0 61 72 74 20 74 6f 20 66 69 6e 69 73 68 2e 0a 2a  art to finish..*
186b0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
186c0 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20  trace(sqlite3*, 
186d0 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f  void(*xTrace)(vo
186e0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  id*,const char*)
186f0 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a  , void*);.void *
18700 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
18710 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
18720 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
18730 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
18740 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
18750 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
18760 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
18770 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
18780 73 20 7b 46 31 32 39 31 30 7d 0a 2a 2a 0a 2a 2a  s {F12910}.**.**
18790 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f   This routine co
187a0 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62  nfigures a callb
187b0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74  ack function - t
187c0 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63  he.** progress c
187d0 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69  allback - that i
187e0 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  s invoked period
187f0 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
18800 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61  ng.** running ca
18810 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
18820 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
18830 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a  3_step()] and.**
18840 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
18850 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d  ble()].  An exam
18860 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
18870 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
18880 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
18890 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
188a0 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
188b0 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72 65  ** If the progre
188c0 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
188d0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
188e0 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
188f0 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
18900 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
18910 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
18920 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
18930 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
18940 47 55 49 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a  GUI dialog box..
18950 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
18960 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 31 7d  :.**.** {F12911}
18970 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
18980 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
18990 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
189a0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a  gress_handler().
189b0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69  **          is i
189c0 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
189d0 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
189e0 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
189f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
18a00 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
18a10 2a 0a 2a 2a 20 7b 46 31 32 39 31 32 7d 20 54 68  *.** {F12912} Th
18a20 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
18a30 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
18a40 6e 63 65 20 66 6f 72 20 65 76 65 72 79 20 4e 20  nce for every N 
18a50 76 69 72 74 75 61 6c 0a 2a 2a 20 20 20 20 20 20  virtual.**      
18a60 20 20 20 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f      machine opco
18a70 64 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20  des, where N is 
18a80 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
18a90 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ent to.**       
18aa0 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f     the [sqlite3_
18ab0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
18ac0 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 72 65  ()] call that re
18ad0 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20  gistered.**     
18ae0 20 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63       the callbac
18af0 6b 2e 20 20 49 66 20 4e 20 69 73 20 6c 65 73 73  k.  If N is less
18b00 20 74 68 61 6e 20 31 2c 20 73 71 6c 69 74 65 33   than 1, sqlite3
18b10 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
18b20 72 28 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r().**          
18b30 61 63 74 73 20 61 73 20 69 66 20 61 20 4e 55 4c  acts as if a NUL
18b40 4c 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  L progress handl
18b50 65 72 20 68 61 64 20 62 65 65 6e 20 73 70 65 63  er had been spec
18b60 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ified..**.** {F1
18b70 32 39 31 33 7d 20 54 68 65 20 70 72 6f 67 72 65  2913} The progre
18b80 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 74 73 65  ss callback itse
18b90 6c 66 20 69 73 20 69 64 65 6e 74 69 66 69 65 64  lf is identified
18ba0 20 62 79 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   by the third.**
18bb0 20 20 20 20 20 20 20 20 20 20 61 72 67 75 6d 65            argume
18bc0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72  nt to sqlite3_pr
18bd0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29  ogress_handler()
18be0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 34 7d  ..**.** {F12914}
18bf0 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   The fourth argu
18c00 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
18c10 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
18c20 28 29 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20  () is a.**      
18c30 20 20 20 20 76 6f 69 64 20 70 6f 69 6e 74 65 72      void pointer
18c40 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 70   passed to the p
18c50 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
18c60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e  .**          fun
18c70 63 74 69 6f 6e 20 65 61 63 68 20 74 69 6d 65 20  ction each time 
18c80 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  it is invoked..*
18c90 2a 0a 2a 2a 20 7b 46 31 32 39 31 35 7d 20 49 66  *.** {F12915} If
18ca0 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
18cb0 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 73 75  te3_step()] resu
18cc0 6c 74 73 20 69 6e 20 66 65 77 65 72 20 74 68 61  lts in fewer tha
18cd0 6e 20 4e 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 20  n N opcodes.**  
18ce0 20 20 20 20 20 20 20 20 62 65 69 6e 67 20 65 78          being ex
18cf0 65 63 75 74 65 64 2c 20 74 68 65 6e 20 74 68 65  ecuted, then the
18d00 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
18d10 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e 76 6f  ck is never invo
18d20 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ked..**.** {F129
18d30 31 36 7d 20 45 76 65 72 79 20 63 61 6c 6c 20 74  16} Every call t
18d40 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  o [sqlite3_progr
18d50 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a 2a  ess_handler()].*
18d60 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65 72 77  *          overw
18d70 72 69 74 65 73 20 61 6e 79 20 70 72 65 76 69 6f  rites any previo
18d80 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 20  usly registered 
18d90 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
18da0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 31 37 7d  ..**.** {F12917}
18db0 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73   If the progress
18dc0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
18dd0 6b 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 6e  k is NULL then n
18de0 6f 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 20 20  o progress.**   
18df0 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20 69         handler i
18e00 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
18e10 20 7b 46 31 32 39 31 38 7d 20 49 66 20 74 68 65   {F12918} If the
18e20 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
18e30 63 6b 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  ck returns a res
18e40 75 6c 74 20 6f 74 68 65 72 20 74 68 61 6e 20 30  ult other than 0
18e50 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
18e60 20 20 20 74 68 65 20 62 65 68 61 76 69 6f 72 20     the behavior 
18e70 69 73 20 61 20 69 66 20 5b 73 71 6c 69 74 65 33  is a if [sqlite3
18e80 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20 68 61  _interrupt()] ha
18e90 64 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a  d been called..*
18ea0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  /.void sqlite3_p
18eb0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
18ec0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
18ed0 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
18ee0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
18ef0 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
18f00 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
18f10 6e 6e 65 63 74 69 6f 6e 20 7b 46 31 32 37 30 30  nnection {F12700
18f20 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  }.**.** These ro
18f30 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
18f40 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
18f50 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69  ile whose name i
18f60 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a  s given by the.*
18f70 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
18f80 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e 61 6d  ent. The filenam
18f90 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
18fa0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
18fb0 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
18fc0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
18fd0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
18fe0 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
18ff0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
19000 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
19010 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 41  ite3_open16(). A
19020 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
19030 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
19040 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
19050 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
19060 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
19070 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
19080 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
19090 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
190a0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
190b0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
190c0 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
190d0 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
190e0 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
190f0 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
19100 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
19110 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
19120 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
19130 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  . If the databas
19140 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
19150 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
19160 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
19170 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
19180 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
19190 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
191a0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
191b0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  ed.  The.** [sql
191c0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
191d0 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
191e0 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
191f0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
19200 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
19210 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
19220 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
19230 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  error..**.** The
19240 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
19250 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  g for the databa
19260 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  se will be UTF-8
19270 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   if.** sqlite3_o
19280 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
19290 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61  _open_v2() is ca
192a0 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d  lled and.** UTF-
192b0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
192c0 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73   byte order if s
192d0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
192e0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57  is used..**.** W
192f0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
19300 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
19310 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
19320 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
19330 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
19340 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
19350 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
19360 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
19370 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
19380 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
19390 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
193a0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
193b0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
193c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
193d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
193e0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
193f0 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
19400 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
19410 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
19420 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
19430 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
19440 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
19450 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
19460 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67  ction.  The flag
19470 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20  s parameter can 
19480 62 65 20 6f 6e 65 20 6f 66 3a 0a 2a 2a 0a 2a 2a  be one of:.**.**
19490 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 51   <dl>.** <dt>[SQ
194a0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
194b0 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
194c0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
194d0 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
194e0 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
194f0 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
19500 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
19510 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
19520 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
19530 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49  .**.** <dt>[SQLI
19540 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
19550 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
19560 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
19570 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
19580 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
19590 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
195a0 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
195b0 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
195c0 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
195d0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
195e0 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
195f0 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
19600 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
19610 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
19620 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
19630 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a  returned.</dd>.*
19640 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45  *.** <dt>[SQLITE
19650 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
19660 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
19670 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  CREATE]</dt>.** 
19680 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
19690 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
196a0 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
196b0 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74  ng, and is creat
196c0 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 64  es it if.** it d
196d0 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20  oes not already 
196e0 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74  exist. This is t
196f0 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  he behavior that
19700 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
19710 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
19720 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
19730 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e  3_open16().</dd>
19740 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
19750 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
19760 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
19770 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
19780 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
19790 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
197a0 6e 20 61 62 6f 76 65 20 74 68 65 6e 20 74 68 65  n above then the
197b0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
197c0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
197d0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
197e0 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
197f0 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
19800 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
19810 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
19820 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
19830 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69  connection.  Thi
19840 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  s in-memory data
19850 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
19860 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74   when.** the dat
19870 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19880 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74   is closed.  Fut
19890 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
198a0 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
198b0 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69  make use of addi
198c0 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66  tional special f
198d0 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65  ilenames that be
198e0 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
198f0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
19900 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
19910 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74   that when a dat
19920 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61  abase filename a
19930 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67  ctually does beg
19940 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22  in with.** a ":"
19950 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73   character you s
19960 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65  hould prefix the
19970 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61   filename with a
19980 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61   pathname such a
19990 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f  s.** "./" to avo
199a0 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
199b0 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e  .** If the filen
199c0 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
199d0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
199e0 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
199f0 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
19a00 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
19a10 65 61 74 65 64 2e 20 20 54 68 69 73 20 70 72 69  eated.  This pri
19a20 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
19a30 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
19a40 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
19a50 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
19a60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19a70 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
19a80 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  ** The fourth pa
19a90 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
19aa0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
19ab0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
19ac0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
19ad0 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
19ae0 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
19af0 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
19b00 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
19b10 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
19b20 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
19b30 73 65 2e 20 20 49 66 20 74 68 65 20 66 6f 75 72  se.  If the four
19b40 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
19b50 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
19b60 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
19b70 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
19b80 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
19b90 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
19ba0 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
19bb0 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
19bc0 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
19bd0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
19be0 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
19bf0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
19c00 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
19c10 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
19c20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
19c30 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
19c40 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
19c50 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
19c60 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
19c70 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
19c80 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
19c90 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
19ca0 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
19cb0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
19cc0 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
19cd0 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
19ce0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
19cf0 2a 2a 20 7b 46 31 32 37 30 31 7d 20 54 68 65 20  ** {F12701} The 
19d00 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
19d10 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
19d20 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20  6()], and.**    
19d30 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f        [sqlite3_o
19d40 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
19d50 61 63 65 73 20 63 72 65 61 74 65 20 61 20 6e 65  aces create a ne
19d60 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  w.**          [d
19d70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19d80 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  on] associated w
19d90 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
19da0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
19db0 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 69 72  e given in their
19dc0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
19dd0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 32 7d  ..**.** {F12702}
19de0 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   The filename ar
19df0 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
19e00 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 0a 2a  reted as UTF-8.*
19e10 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 5b  *          for [
19e20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
19e30 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  and [sqlite3_ope
19e40 6e 5f 76 32 28 29 5d 20 61 6e 64 20 61 73 20 55  n_v2()] and as U
19e50 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20 20  TF-16.**        
19e60 20 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20    in the native 
19e70 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 5b  byte order for [
19e80 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
19e90 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30 33  ]..**.** {F12703
19ea0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
19eb0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
19ec0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
19ed0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
19ee0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ],.**          o
19ef0 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
19f00 76 32 28 29 5d 20 77 72 69 74 65 73 20 61 20 70  v2()] writes a p
19f10 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a  ointer to a new.
19f20 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
19f30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19f40 5d 20 69 6e 74 6f 20 2a 70 70 44 62 2e 0a 2a 2a  ] into *ppDb..**
19f50 0a 2a 2a 20 7b 46 31 32 37 30 34 7d 20 54 68 65  .** {F12704} The
19f60 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
19f70 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
19f80 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20  16()], and.**   
19f90 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
19fa0 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
19fb0 66 61 63 65 73 20 72 65 74 75 72 6e 20 5b 53 51  faces return [SQ
19fc0 4c 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e 20 73 75  LITE_OK] upon su
19fd0 63 63 65 73 73 2c 0a 2a 2a 20 20 20 20 20 20 20  ccess,.**       
19fe0 20 20 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72     or an appropr
19ff0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
1a000 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  ] on failure..**
1a010 0a 2a 2a 20 7b 46 31 32 37 30 36 7d 20 54 68 65  .** {F12706} The
1a020 20 64 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e   default text en
1a030 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77  coding for a new
1a040 20 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65   database create
1a050 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
1a060 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65      [sqlite3_ope
1a070 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  n()] or [sqlite3
1a080 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 69 6c 6c  _open_v2()] will
1a090 20 62 65 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a   be UTF-8..**.**
1a0a0 20 7b 46 31 32 37 30 37 7d 20 54 68 65 20 64 65   {F12707} The de
1a0b0 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64  fault text encod
1a0c0 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61  ing for a new da
1a0d0 74 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75  tabase created u
1a0e0 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
1a0f0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1a100 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ()] will be UTF-
1a110 31 36 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 30  16..**.** {F1270
1a120 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
1a130 6f 70 65 6e 28 46 2c 44 29 5d 20 69 6e 74 65 72  open(F,D)] inter
1a140 66 61 63 65 20 69 73 20 65 71 75 69 76 61 6c 65  face is equivale
1a150 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  nt to.**        
1a160 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f    [sqlite3_open_
1a170 76 32 28 46 2c 44 2c 47 2c 30 29 5d 20 77 68 65  v2(F,D,G,0)] whe
1a180 72 65 20 74 68 65 20 47 20 70 61 72 61 6d 65 74  re the G paramet
1a190 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  er is.**        
1a1a0 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52    [SQLITE_OPEN_R
1a1b0 45 41 44 57 52 49 54 45 5d 7c 5b 53 51 4c 49 54  EADWRITE]|[SQLIT
1a1c0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 0a  E_OPEN_CREATE]..
1a1d0 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 31 7d 20 49  **.** {F12711} I
1a1e0 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65  f the G paramete
1a1f0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r to [sqlite3_op
1a200 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20  en_v2(F,D,G,V)] 
1a210 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20  contains the.** 
1a220 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c           bit val
1a230 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ue [SQLITE_OPEN_
1a240 52 45 41 44 4f 4e 4c 59 5d 20 74 68 65 6e 20 74  READONLY] then t
1a250 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1a260 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  pened.**        
1a270 20 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e    for reading on
1a280 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31  ly..**.** {F1271
1a290 32 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61  2} If the G para
1a2a0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
1a2b0 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c  3_open_v2(F,D,G,
1a2c0 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  V)] contains the
1a2d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74  .**          bit
1a2e0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f   value [SQLITE_O
1a2f0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 74  PEN_READWRITE] t
1a300 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
1a310 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20   is opened.**   
1a320 20 20 20 20 20 20 20 72 65 61 64 69 6e 67 20 61         reading a
1a330 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
1a340 73 73 69 62 6c 65 2c 20 6f 72 20 66 6f 72 20 72  ssible, or for r
1a350 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 20 74  eading only if t
1a360 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  he.**          f
1a370 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
1a380 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
1a390 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 0a  erating system..
1a3a0 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 33 7d 20 49  **.** {F12713} I
1a3b0 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65  f the G paramete
1a3c0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r to [sqlite3_op
1a3d0 65 6e 28 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20  en(v2(F,D,G,V)] 
1a3e0 6f 6d 69 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  omits the.**    
1a3f0 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20        bit value 
1a400 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
1a410 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74  ATE] and the dat
1a420 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
1a430 2a 20 20 20 20 20 20 20 20 20 20 70 72 65 76 69  *          previ
1a440 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 61 6e 20  ously exist, an 
1a450 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1a460 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 31 34  d..**.** {F12714
1a470 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d  } If the G param
1a480 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
1a490 5f 6f 70 65 6e 28 76 32 28 46 2c 44 2c 47 2c 56  _open(v2(F,D,G,V
1a4a0 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a  )] contains the.
1a4b0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20  **          bit 
1a4c0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50  value [SQLITE_OP
1a4d0 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 74  EN_CREATE] and t
1a4e0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
1a4f0 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20   not.**         
1a500 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73   previously exis
1a510 74 2c 20 74 68 65 6e 20 61 6e 20 61 74 74 65 6d  t, then an attem
1a520 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 63 72  pt is made to cr
1a530 65 61 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20  eate and.**     
1a540 20 20 20 20 20 69 6e 69 74 69 61 6c 69 7a 65 20       initialize 
1a550 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a  the database..**
1a560 0a 2a 2a 20 7b 46 31 32 37 31 37 7d 20 49 66 20  .** {F12717} If 
1a570 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
1a580 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
1a590 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
1a5a0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a  te3_open16()],.*
1a5b0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
1a5c0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1a5d0 5d 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  ] is ":memory:",
1a5e0 20 74 68 65 6e 20 61 6e 20 70 72 69 76 61 74 65   then an private
1a5f0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70  ,.**          ep
1a600 68 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d 65 6d 6f  hemeral, in-memo
1a610 72 79 20 64 61 74 61 62 61 73 65 20 69 73 20 63  ry database is c
1a620 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
1a630 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 20 20 20  onnection..**   
1a640 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20         <todo>Is 
1a650 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1a660 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  TE|SQLITE_OPEN_R
1a670 45 41 44 57 52 49 54 45 20 72 65 71 75 69 72 65  EADWRITE require
1a680 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  d.**          in
1a690 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1a6a0 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  ()?</todo>.**.**
1a6b0 20 7b 46 31 32 37 31 39 7d 20 49 66 20 74 68 65   {F12719} If the
1a6c0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 4e 55 4c   filename is NUL
1a6d0 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74  L or an empty st
1a6e0 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
1a6f0 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20  vate,.**        
1a700 20 20 65 70 68 65 6d 65 72 61 6c 20 6f 6e 2d 64    ephemeral on-d
1a710 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
1a720 6c 20 62 65 20 63 72 65 61 74 65 64 2e 0a 2a 2a  l be created..**
1a730 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e            <todo>
1a740 49 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  Is SQLITE_OPEN_C
1a750 52 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45  REATE|SQLITE_OPE
1a760 4e 5f 52 45 41 44 57 52 49 54 45 20 72 65 71 75  N_READWRITE requ
1a770 69 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ired.**         
1a780 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
1a790 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a  _v2()?</todo>.**
1a7a0 0a 2a 2a 20 7b 46 31 32 37 32 31 7d 20 54 68 65  .** {F12721} The
1a7b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1a7c0 63 74 69 6f 6e 5d 20 63 72 65 61 74 65 64 20 62  ction] created b
1a7d0 79 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  y [sqlite3_open_
1a7e0 76 32 28 46 2c 44 2c 47 2c 56 29 5d 0a 2a 2a 20  v2(F,D,G,V)].** 
1a7f0 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 75 73           will us
1a800 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  e the [sqlite3_v
1a810 66 73 5d 20 6f 62 6a 65 63 74 20 69 64 65 6e 74  fs] object ident
1a820 69 66 69 65 64 20 62 79 20 74 68 65 20 56 20 70  ified by the V p
1a830 61 72 61 6d 65 74 65 72 2c 0a 2a 2a 20 20 20 20  arameter,.**    
1a840 20 20 20 20 20 20 6f 72 20 74 68 65 20 64 65 66        or the def
1a850 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
1a860 73 5d 20 6f 62 6a 65 63 74 20 69 66 20 56 20 69  s] object if V i
1a870 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1a880 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 32 33 7d  ..**.** {F12723}
1a890 20 54 77 6f 20 5b 64 61 74 61 62 61 73 65 20 63   Two [database c
1a8a0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 77 69 6c 6c  onnections] will
1a8b0 20 73 68 61 72 65 20 61 20 63 6f 6d 6d 6f 6e 20   share a common 
1a8c0 63 61 63 68 65 20 69 66 20 62 6f 74 68 20 77 65  cache if both we
1a8d0 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  re.**          o
1a8e0 70 65 6e 65 64 20 77 69 74 68 20 74 68 65 20 73  pened with the s
1a8f0 61 6d 65 20 56 46 53 20 77 68 69 6c 65 20 5b 73  ame VFS while [s
1a900 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
1a910 5d 20 77 61 73 20 65 6e 61 62 6c 65 64 20 61 6e  ] was enabled an
1a920 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66  d.**          if
1a930 20 62 6f 74 68 20 66 69 6c 65 6e 61 6d 65 73 20   both filenames 
1a940 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 75 73  compare equal us
1a950 69 6e 67 20 6d 65 6d 63 6d 70 28 29 20 61 66 74  ing memcmp() aft
1a960 65 72 20 68 61 76 69 6e 67 20 62 65 65 6e 0a 2a  er having been.*
1a970 2a 20 20 20 20 20 20 20 20 20 20 70 72 6f 63 65  *          proce
1a980 73 73 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ssed by the [sql
1a990 69 74 65 33 5f 76 66 73 20 7c 20 78 46 75 6c 6c  ite3_vfs | xFull
1a9a0 50 61 74 68 6e 61 6d 65 5d 20 6d 65 74 68 6f 64  Pathname] method
1a9b0 20 6f 66 20 74 68 65 20 56 46 53 2e 0a 2a 2f 0a   of the VFS..*/.
1a9c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
1a9d0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
1a9e0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
1a9f0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1aa00 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
1aa10 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
1aa20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1aa30 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1aa40 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1aa50 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
1aa60 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
1aa70 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
1aa80 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
1aa90 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1aaa0 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
1aab0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1aac0 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
1aad0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1aae0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
1aaf0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
1ab00 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1ab10 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
1ab20 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
1ab30 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1ab40 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1ab50 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
1ab60 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
1ab70 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
1ab80 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
1ab90 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
1aba0 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
1abb0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
1abc0 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
1abd0 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 20 7b  s And Messages {
1abe0 46 31 32 38 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68  F12800}.**.** Th
1abf0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
1ac00 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
1ac10 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
1ac20 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
1ac30 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
1ac40 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
1ac50 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1ac60 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f   failed sqlite3_
1ac70 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73  * API call.** as
1ac80 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
1ac90 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1aca0 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f  tion]. If a prio
1acb0 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
1acc0 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73  d.** but the mos
1acd0 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
1ace0 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
1acf0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
1ad00 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72  om.** sqlite3_er
1ad10 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
1ad20 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ined..**.** The 
1ad30 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1ad40 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72   and sqlite3_err
1ad50 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45  msg16() return E
1ad60 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a  nglish-language.
1ad70 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73  ** text that des
1ad80 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
1ad90 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  , as either UTF-
1ada0 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70  8 or UTF-16 resp
1adb0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d  ectively..** Mem
1adc0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1add0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
1ade0 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
1adf0 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54  internally..** T
1ae00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
1ae10 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
1ae20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65  worry about free
1ae30 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a  ing the result..
1ae40 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
1ae50 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67  error string mig
1ae60 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ht be overwritte
1ae70 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
1ae80 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e   by.** subsequen
1ae90 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72  t calls to other
1aea0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
1aeb0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  e functions..**.
1aec0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1aed0 2a 0a 2a 2a 20 7b 46 31 32 38 30 31 7d 20 54 68  *.** {F12801} Th
1aee0 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  e [sqlite3_errco
1aef0 64 65 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65  de(D)] interface
1af00 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1af10 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20  eric.**         
1af20 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
1af30 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  r [extended resu
1af40 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  lt code] for the
1af50 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 0a 2a   most recently.*
1af60 2a 20 20 20 20 20 20 20 20 20 20 66 61 69 6c 65  *          faile
1af70 64 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c  d interface call
1af80 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1af90 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
1afa0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
1afb0 0a 2a 2a 20 7b 46 31 32 38 30 33 7d 20 54 68 65  .** {F12803} The
1afc0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1afd0 28 44 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  (D)] and [sqlite
1afe0 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d 0a 2a  3_errmsg16(D)].*
1aff0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
1b000 66 61 63 65 73 20 72 65 74 75 72 6e 20 45 6e 67  faces return Eng
1b010 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65  lish-language te
1b020 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
1b030 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
1b040 65 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 6d  e error in the m
1b050 6f 73 74 6c 79 20 72 65 63 65 6e 74 6c 79 20 66  ostly recently f
1b060 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20  ailed interface 
1b070 63 61 6c 6c 2c 0a 2a 2a 20 20 20 20 20 20 20 20  call,.**        
1b080 20 20 65 6e 63 6f 64 65 64 20 61 73 20 65 69 74    encoded as eit
1b090 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
1b0a0 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  -16 respectively
1b0b0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 37 7d  ..**.** {F12807}
1b0c0 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
1b0d0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1b0e0 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20  3_errmsg()] and 
1b0f0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
1b100 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  6()].**         
1b110 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
1b120 20 74 68 65 20 6e 65 78 74 20 53 51 4c 69 74 65   the next SQLite
1b130 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2e   interface call.
1b140 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 38 7d 20  .**.** {F12808} 
1b150 43 61 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f 75  Calls to API rou
1b160 74 69 6e 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  tines that do no
1b170 74 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  t return an erro
1b180 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20  r code.**       
1b190 20 20 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71     (example: [sq
1b1a0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
1b1b0 28 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20  ()]) do not.**  
1b1c0 20 20 20 20 20 20 20 20 63 68 61 6e 67 65 20 74          change t
1b1d0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 72  he error code or
1b1e0 20 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e 65   message returne
1b1f0 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
1b200 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1b210 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65  e()], [sqlite3_e
1b220 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71  rrmsg()], or [sq
1b230 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1b240 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 38 30 39  ]..**.** {F12809
1b250 7d 20 49 6e 74 65 72 66 61 63 65 73 20 74 68 61  } Interfaces tha
1b260 74 20 61 72 65 20 6e 6f 74 20 61 73 73 6f 63 69  t are not associ
1b270 61 74 65 64 20 77 69 74 68 20 61 20 73 70 65 63  ated with a spec
1b280 69 66 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20  ific.**         
1b290 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1b2a0 63 74 69 6f 6e 5d 20 28 65 78 61 6d 70 6c 65 73  ction] (examples
1b2b0 3a 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  :.**          [s
1b2c0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
1b2d0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 6e  ] or [sqlite3_en
1b2e0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
1b2f0 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  e()].**         
1b300 20 64 6f 20 6e 6f 74 20 63 68 61 6e 67 65 20 74   do not change t
1b310 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
1b320 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
1b330 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f    [sqlite3_errco
1b340 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  de()], [sqlite3_
1b350 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73  errmsg()], or [s
1b360 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1b370 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
1b380 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
1b390 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63  e3 *db);.const c
1b3a0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
1b3b0 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  msg(sqlite3*);.c
1b3c0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
1b3d0 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
1b3e0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1b3f0 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74  PI3REF: SQL Stat
1b400 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 46 31  ement Object {F1
1b410 33 30 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  3000}.** KEYWORD
1b420 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
1b430 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
1b440 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
1b450 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
1b460 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
1b470 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
1b480 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
1b490 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
1b4a0 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e   is variously kn
1b4b0 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72  own as a "prepar
1b4c0 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  ed statement" or
1b4d0 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20   a.** "compiled 
1b4e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
1b4f0 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
1b500 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a  tatement"..**.**
1b510 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
1b520 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
1b530 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
1b540 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
1b550 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
1b560 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
1b570 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
1b580 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
1b590 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
1b5a0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
1b5b0 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
1b5c0 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  o [host paramete
1b5d0 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
1b5e0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
1b5f0 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
1b600 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
1b610 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
1b620 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
1b630 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
1b640 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
1b650 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  set the statemen
1b660 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1b670 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
1b680 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
1b690 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
1b6a0 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
1b6b0 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
1b6c0 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
1b6d0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1b6e0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
1b6f0 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66   </ol>.**.** Ref
1b700 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74  er to documentat
1b710 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
1b720 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  l methods above 
1b730 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
1b740 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
1b750 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
1b760 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
1b770 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
1b780 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1b790 2d 74 69 6d 65 20 4c 69 6d 69 74 73 20 7b 46 31  -time Limits {F1
1b7a0 32 37 36 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  2760}.**.** This
1b7b0 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
1b7c0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61  s the size of va
1b7d0 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73  rious constructs
1b7e0 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a   to be limited.*
1b7f0 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f  * on a connectio
1b800 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  n by connection 
1b810 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73  basis.  The firs
1b820 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
1b830 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
1b840 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73  connection] whos
1b850 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65  e limit is to be
1b860 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e   set or queried.
1b870 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
1b880 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65  parameter is one
1b890 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63   of the [limit c
1b8a0 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20  ategories] that 
1b8b0 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73  define a.** clas
1b8c0 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20  s of constructs 
1b8d0 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74  to be size limit
1b8e0 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70  ed.  The third p
1b8f0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
1b900 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72  ** new limit for
1b910 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e   that construct.
1b920 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 72    The function r
1b930 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c  eturns the old l
1b940 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  imit..**.** If t
1b950 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
1b960 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
1b970 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
1b980 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f  unchanged..** Fo
1b990 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74 65  r the limit cate
1b9a0 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c  gory of SQLITE_L
1b9b0 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20 69  IMIT_XYZ there i
1b9c0 73 20 61 20 68 61 72 64 20 75 70 70 65 72 0a 2a  s a hard upper.*
1b9d0 2a 20 62 6f 75 6e 64 20 73 65 74 20 62 79 20 61  * bound set by a
1b9e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20   compile-time C 
1b9f0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1ba00 72 6f 20 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f  ro named SQLITE_
1ba10 4d 41 58 5f 58 59 5a 2e 0a 2a 2a 20 28 54 68 65  MAX_XYZ..** (The
1ba20 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68   "_LIMIT_" in th
1ba30 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65  e name is change
1ba40 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a  d to "_MAX_".).*
1ba50 2a 20 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e  * Attempts to in
1ba60 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
1ba70 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
1ba80 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
1ba90 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
1baa0 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
1bab0 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a  upper limit..**.
1bac0 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69  ** Run time limi
1bad0 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ts are intended 
1bae0 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69  for use in appli
1baf0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e  cations that man
1bb00 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69  age.** both thei
1bb10 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64  r own internal d
1bb20 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f  atabase and also
1bb30 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20   databases that 
1bb40 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a  are controlled.*
1bb50 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65  * by untrusted e
1bb60 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e  xternal sources.
1bb70 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70    An example app
1bb80 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62  lication might b
1bb90 65 20 61 0a 2a 2a 20 77 65 62 62 72 6f 77 73 65  e a.** webbrowse
1bba0 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
1bbb0 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
1bbc0 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
1bbd0 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
1bbe0 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
1bbf0 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
1bc00 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
1bc10 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
1bc20 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
1bc30 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
1bc40 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
1bc50 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
1bc60 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
1bc70 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
1bc80 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
1bc90 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
1bca0 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
1bcb0 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
1bcc0 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
1bcd0 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
1bce0 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
1bcf0 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
1bd00 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
1bd10 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
1bd20 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1bd30 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
1bd40 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
1bd50 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
1bd60 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
1bd70 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
1bd80 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
1bd90 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
1bda0 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
1bdb0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
1bdc0 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
1bdd0 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  RAGMA]..**.** Th
1bde0 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
1bdf0 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64  currently consid
1be00 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61  ered experimenta
1be10 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63 74  l and is subject
1be20 0a 2a 2a 20 74 6f 20 63 68 61 6e 67 65 20 6f 72  .** to change or
1be30 20 72 65 6d 6f 76 61 6c 20 77 69 74 68 6f 75 74   removal without
1be40 20 70 72 69 6f 72 20 6e 6f 74 69 63 65 2e 0a 2a   prior notice..*
1be50 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
1be60 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 37 36 32 7d 20  .**.** {F12762} 
1be70 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
1be80 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69  l to [sqlite3_li
1be90 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 72  mit(D,C,V)] wher
1bea0 65 20 56 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  e V is.**       
1beb0 20 20 20 70 6f 73 69 74 69 76 65 20 63 68 61 6e     positive chan
1bec0 67 65 73 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e  ges the limit on
1bed0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e   the size of con
1bee0 73 74 72 75 63 74 20 43 20 69 6e 20 74 68 65 0a  struct C in the.
1bef0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
1bf00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1bf10 5d 20 44 20 74 6f 20 74 68 65 20 6c 65 73 73 65  ] D to the lesse
1bf20 72 20 6f 66 20 56 20 61 6e 64 20 74 68 65 20 68  r of V and the h
1bf30 61 72 64 20 75 70 70 65 72 0a 2a 2a 20 20 20 20  ard upper.**    
1bf40 20 20 20 20 20 20 62 6f 75 6e 64 20 6f 6e 20 74        bound on t
1bf50 68 65 20 73 69 7a 65 20 6f 66 20 43 20 74 68 61  he size of C tha
1bf60 74 20 69 73 20 73 65 74 20 61 74 20 63 6f 6d 70  t is set at comp
1bf70 69 6c 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ile-time..**.** 
1bf80 7b 46 31 32 37 36 36 7d 20 41 20 73 75 63 63 65  {F12766} A succe
1bf90 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
1bfa0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43  qlite3_limit(D,C
1bfb0 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69 73 20  ,V)] where V is 
1bfc0 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20  negative.**     
1bfd0 20 20 20 20 20 6c 65 61 76 65 73 20 74 68 65 20       leaves the 
1bfe0 73 74 61 74 65 20 6f 66 20 74 68 65 20 5b 64 61  state of the [da
1bff0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c000 6e 5d 20 44 20 75 6e 63 68 61 6e 67 65 64 2e 0a  n] D unchanged..
1c010 2a 2a 0a 2a 2a 20 7b 46 31 32 37 36 39 7d 20 41  **.** {F12769} A
1c020 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
1c030 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   to [sqlite3_lim
1c040 69 74 28 44 2c 43 2c 56 29 5d 20 72 65 74 75 72  it(D,C,V)] retur
1c050 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
1c060 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20     value of the 
1c070 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a  limit on the siz
1c080 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43  e of construct C
1c090 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   in the.**      
1c0a0 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
1c0b0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 61 73 20 69  nnection] D as i
1c0c0 74 20 77 61 73 20 70 72 69 6f 72 20 74 6f 20 74  t was prior to t
1c0d0 68 65 20 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20  he call..*/.int 
1c0e0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
1c0f0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
1c100 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
1c110 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
1c120 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
1c130 65 67 6f 72 69 65 73 20 7b 46 31 32 37 39 30 7d  egories {F12790}
1c140 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
1c150 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
1c160 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
1c170 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
1c180 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
1c190 61 72 69 6f 75 73 20 61 73 70 65 63 74 73 20 6f  arious aspects o
1c1a0 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  f a [database co
1c1b0 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61  nnection].** tha
1c1c0 74 20 63 61 6e 20 62 65 20 6c 69 6d 69 74 65 64  t can be limited
1c1d0 20 69 6e 20 73 69 7a 65 20 62 79 20 63 61 6c 6c   in size by call
1c1e0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69  s to [sqlite3_li
1c1f0 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 6d  mit()]..** The m
1c200 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
1c210 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 61 72  arious limits ar
1c220 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  e as follows:.**
1c230 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
1c240 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
1c250 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
1c260 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
1c270 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
1c280 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
1c290 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  row.<dd>.**.** <
1c2a0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1c2b0 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
1c2c0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1c2d0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
1c2e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  SQL statement.</
1c2f0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
1c300 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
1c310 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
1c320 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1c330 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
1c340 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
1c350 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
1c360 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 53  esult set of a S
1c370 45 4c 45 43 54 20 6f 72 20 74 68 65 20 6d 61 78  ELECT or the max
1c380 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
1c390 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
1c3a0 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
1c3b0 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
1c3c0 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
1c3d0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1c3e0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
1c3f0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1c400 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
1c410 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
1c420 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
1c430 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  sion.</dd>.**.**
1c440 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1c450 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
1c460 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
1c470 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1c480 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63   of terms in a c
1c490 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73  ompound SELECT s
1c4a0 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a  tatement.</dd>.*
1c4b0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1c4c0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
1c4d0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1c4e0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1c4f0 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
1c500 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
1c510 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
1c520 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
1c530 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
1c540 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1c550 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
1c560 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
1c570 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1c580 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
1c590 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
1c5a0 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
1c5b0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1c5c0 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
1c5d0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1c5e0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 74 74 61  m number of atta
1c5f0 63 68 65 64 20 64 61 74 61 62 61 73 65 73 2e 3c  ched databases.<
1c600 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1c610 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
1c620 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c  _PATTERN_LENGTH<
1c630 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1c640 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
1c650 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72  f the pattern ar
1c660 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 4c 49  gument to the LI
1c670 4b 45 20 6f 72 0a 2a 2a 20 47 4c 4f 42 20 6f 70  KE or.** GLOB op
1c680 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a  erators.</dd>.**
1c690 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
1c6a0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1c6b0 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
1c6c0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1c6d0 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73  ber of variables
1c6e0 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
1c6f0 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a  ment that can.**
1c700 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a   be bound.</dd>.
1c710 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
1c720 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1c730 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
1c740 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
1c750 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1c760 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
1c770 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
1c780 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1c790 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
1c7a0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
1c7b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1c7c0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
1c7d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
1c7e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1c7f0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
1c800 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
1c810 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c820 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
1c830 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c840 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
1c850 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
1c860 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
1c870 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
1c880 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
1c890 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c8a0 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
1c8b0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
1c8c0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
1c8d0 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
1c8e0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
1c8f0 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
1c900 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      9../*.** CAP
1c910 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
1c920 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
1c930 74 20 7b 46 31 33 30 31 30 7d 0a 2a 2a 20 4b 45  t {F13010}.** KE
1c940 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
1c950 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
1c960 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
1c970 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
1c980 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
1c990 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
1c9a0 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
1c9b0 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
1c9c0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
1c9d0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
1c9e0 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
1c9f0 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
1ca00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
1ca10 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
1ca20 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b   prior call to [
1ca30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
1ca40 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1ca50 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
1ca60 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _open16()]..**.*
1ca70 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
1ca80 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
1ca90 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
1caa0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
1cab0 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
1cac0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
1cad0 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
1cae0 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
1caf0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1cb00 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
1cb10 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
1cb20 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
1cb30 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
1cb40 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1cb50 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
1cb60 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42  .**.** If the nB
1cb70 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  yte argument is 
1cb80 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20  less than zero, 
1cb90 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61  then zSql is rea
1cba0 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66  d up to the.** f
1cbb0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
1cbc0 61 74 6f 72 2e 20 49 66 20 6e 42 79 74 65 20 69  ator. If nByte i
1cbd0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
1cbe0 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d  then it is the m
1cbf0 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72  aximum.** number
1cc00 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20   of  bytes read 
1cc10 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e  from zSql.  When
1cc20 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
1cc30 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a  gative, the.** z
1cc40 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20  Sql string ends 
1cc50 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69  at either the fi
1cc60 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c  rst '\000' or '\
1cc70 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72  u0000' character
1cc80 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65   or.** the nByte
1cc90 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65  -th byte, whiche
1cca0 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e  ver comes first.
1ccb0 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b   If the caller k
1ccc0 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65  nows.** that the
1ccd0 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67   supplied string
1cce0 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74   is nul-terminat
1ccf0 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69  ed, then there i
1cd00 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72  s a small.** per
1cd10 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61  formance advanta
1cd20 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20  ge to be gained 
1cd30 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42  by passing an nB
1cd40 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  yte parameter th
1cd50 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74  at.** is equal t
1cd60 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  o the number of 
1cd70 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70  bytes in the inp
1cd80 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63  ut string <i>inc
1cd90 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68  luding</i>.** th
1cda0 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72  e nul-terminator
1cdb0 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 2a 70   bytes..**.** *p
1cdc0 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
1cdd0 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
1cde0 72 73 74 20 62 79 74 65 20 70 61 73 74 20 74 68  rst byte past th
1cdf0 65 20 65 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20  e end of the.** 
1ce00 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
1ce10 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
1ce20 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
1ce30 79 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  y compile the fi
1ce40 72 73 74 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  rst.** statement
1ce50 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
1ce60 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
1ce70 6e 74 69 6e 67 20 74 6f 20 77 68 61 74 20 72 65  nting to what re
1ce80 6d 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69  mains.** uncompi
1ce90 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74  led..**.** *ppSt
1cea0 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  mt is left point
1ceb0 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65  ing to a compile
1cec0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
1ced0 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20  ement] that can 
1cee0 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75  be.** executed u
1cef0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  sing [sqlite3_st
1cf00 65 70 28 29 5d 2e 20 20 49 66 20 74 68 65 72 65  ep()].  If there
1cf10 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70   is an error, *p
1cf20 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20  pStmt is set.** 
1cf30 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65  to NULL.  If the
1cf40 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
1cf50 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
1cf60 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20  the input is an 
1cf70 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20  empty.** string 
1cf80 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
1cf90 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
1cfa0 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 55  t to NULL..** {U
1cfb0 31 33 30 31 38 7d 20 54 68 65 20 63 61 6c 6c 69  13018} The calli
1cfc0 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
1cfd0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
1cfe0 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
1cff0 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
1d000 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
1d010 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1d020 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
1d030 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
1d040 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73  .**.** On succes
1d050 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  s, [SQLITE_OK] i
1d060 73 20 72 65 74 75 72 6e 65 64 2c 20 6f 74 68 65  s returned, othe
1d070 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
1d080 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
1d090 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1d0a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1d0b0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
1d0c0 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74  epare16_v2() int
1d0d0 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72  erfaces are.** r
1d0e0 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61  ecommended for a
1d0f0 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e  ll new programs.
1d100 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69   The two older i
1d110 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65  nterfaces are re
1d120 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61  tained.** for ba
1d130 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1d140 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72  ility, but their
1d150 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61   use is discoura
1d160 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22  ged..** In the "
1d170 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
1d180 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
1d190 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
1d1a0 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
1d1b0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
1d1c0 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
1d1d0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
1d1e0 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
1d1f0 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
1d200 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
1d210 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
1d220 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69  o.** behave a di
1d230 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f  fferently in two
1d240 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
1d250 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20  >.** <li>.** If 
1d260 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
1d270 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
1d280 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
1d290 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
1d2a0 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
1d2b0 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
1d2c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
1d2d0 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
1d2e0 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
1d2f0 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
1d300 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
1d310 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68  it again.  If th
1d320 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61  e schema has cha
1d330 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79  nged in.** a way
1d340 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20   that makes the 
1d350 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e  statement no lon
1d360 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69  ger valid, [sqli
1d370 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
1d380 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e   still.** return
1d390 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1d3a0 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68  .  But unlike th
1d3b0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
1d3c0 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  r, [SQLITE_SCHEM
1d3d0 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66  A] is.** now a f
1d3e0 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c  atal error.  Cal
1d3f0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  ling [sqlite3_pr
1d400 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69  epare_v2()] agai
1d410 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20  n will not make 
1d420 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20  the.** error go 
1d430 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65  away.  Note: use
1d440 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1d450 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ()] to find the 
1d460 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70  text.** of the p
1d470 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61  arsing error tha
1d480 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20  t results in an 
1d490 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
1d4a0 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e  return..** </li>
1d4b0 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57  .**.** <li>.** W
1d4c0 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
1d4d0 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  urs, [sqlite3_st
1d4e0 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
1d4f0 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
1d500 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20  ailed.** [error 
1d510 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
1d520 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
1d530 2e 20 20 54 68 65 20 6c 65 67 61 63 79 20 62 65  .  The legacy be
1d540 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a  havior was that.
1d550 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
1d560 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
1d570 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20  eturn a generic 
1d580 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
1d590 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e  esult code.** an
1d5a0 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65  d you would have
1d5b0 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
1d5c0 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
1d5d0 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f  e3_reset()] in o
1d5e0 72 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20  rder.** to find 
1d5f0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
1d600 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
1d610 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
1d620 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
1d630 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
1d640 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
1d650 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
1d660 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
1d670 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
1d680 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ol>.**.** I
1d690 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1d6a0 20 7b 46 31 33 30 31 31 7d 20 54 68 65 20 5b 73   {F13011} The [s
1d6b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 64  qlite3_prepare(d
1d6c0 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64  b,zSql,...)] and
1d6d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1d6e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1d6f0 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69  (db,zSql,...)] i
1d700 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65 72 70  nterfaces interp
1d710 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ret the.**      
1d720 20 20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69      text in thei
1d730 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72  r zSql parameter
1d740 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a   as UTF-8..**.**
1d750 20 7b 46 31 33 30 31 32 7d 20 54 68 65 20 5b 73   {F13012} The [s
1d760 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1d770 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61  (db,zSql,...)] a
1d780 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
1d790 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1d7a0 36 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e  6_v2(db,zSql,...
1d7b0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e  )] interfaces in
1d7c0 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20  terpret the.**  
1d7d0 20 20 20 20 20 20 20 20 74 65 78 74 20 69 6e 20          text in 
1d7e0 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d  their zSql param
1d7f0 65 74 65 72 20 61 73 20 55 54 46 2d 31 36 20 69  eter as UTF-16 i
1d800 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
1d810 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  e order..**.** {
1d820 46 31 33 30 31 33 7d 20 49 66 20 74 68 65 20 6e  F13013} If the n
1d830 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f  Byte argument to
1d840 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1d850 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79  e_v2(db,zSql,nBy
1d860 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  te,...)].**     
1d870 20 20 20 20 20 61 6e 64 20 69 74 73 20 76 61 72       and its var
1d880 69 61 6e 74 73 20 69 73 20 6c 65 73 73 20 74 68  iants is less th
1d890 61 6e 20 7a 65 72 6f 2c 20 74 68 65 20 53 51 4c  an zero, the SQL
1d8a0 20 74 65 78 74 20 69 73 0a 2a 2a 20 20 20 20 20   text is.**     
1d8b0 20 20 20 20 20 72 65 61 64 20 66 72 6f 6d 20 7a       read from z
1d8c0 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
1d8d0 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
1d8e0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
1d8f0 2a 2a 20 7b 46 31 33 30 31 34 7d 20 49 66 20 74  ** {F13014} If t
1d900 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
1d910 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
1d920 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c  epare_v2(db,zSql
1d930 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20  ,nByte,...)].** 
1d940 20 20 20 20 20 20 20 20 20 61 6e 64 20 69 74 73           and its
1d950 20 76 61 72 69 61 6e 74 73 20 69 73 20 6e 6f 6e   variants is non
1d960 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
1d970 61 74 20 6d 6f 73 74 20 6e 42 79 74 65 73 20 62  at most nBytes b
1d980 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20  ytes of.**      
1d990 20 20 20 20 53 51 4c 20 74 65 78 74 20 69 73 20      SQL text is 
1d9a0 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 0a  read from zSql..
1d9b0 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31 35 7d 20 49  **.** {F13015} I
1d9c0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
1d9d0 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c  re_v2(db,zSql,N,
1d9e0 50 2c 70 7a 54 61 69 6c 29 5d 20 61 6e 64 20 69  P,pzTail)] and i
1d9f0 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 20  ts variants.**  
1da00 20 20 20 20 20 20 20 20 69 66 20 74 68 65 20 7a          if the z
1da10 53 71 6c 20 69 6e 70 75 74 20 74 65 78 74 20 63  Sql input text c
1da20 6f 6e 74 61 69 6e 73 20 6d 6f 72 65 20 74 68 61  ontains more tha
1da30 6e 20 6f 6e 65 20 53 51 4c 20 73 74 61 74 65 6d  n one SQL statem
1da40 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ent.**          
1da50 61 6e 64 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f  and pzTail is no
1da60 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a 70 7a  t NULL, then *pz
1da70 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20  Tail is made to 
1da80 70 6f 69 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20  point to the.** 
1da90 20 20 20 20 20 20 20 20 20 66 69 72 73 74 20 62           first b
1daa0 79 74 65 20 70 61 73 74 20 74 68 65 20 65 6e 64  yte past the end
1dab0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51   of the first SQ
1dac0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
1dad0 53 71 6c 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  Sql..**         
1dae0 20 3c 74 6f 64 6f 3e 57 68 61 74 20 64 6f 65 73   <todo>What does
1daf0 20 2a 70 7a 54 61 69 6c 20 70 6f 69 6e 74 20 74   *pzTail point t
1db00 6f 20 69 66 20 74 68 65 72 65 20 69 73 20 6f 6e  o if there is on
1db10 65 20 73 74 61 74 65 6d 65 6e 74 3f 3c 2f 74 6f  e statement?</to
1db20 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 30 31  do>.**.** {F1301
1db30 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  6} A successful 
1db40 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1db50 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a  _prepare_v2(db,z
1db60 53 71 6c 2c 4e 2c 70 70 53 74 6d 74 2c 2e 2e 2e  Sql,N,ppStmt,...
1db70 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
1db80 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
1db90 69 61 6e 74 73 20 77 72 69 74 65 73 20 69 6e 74  iants writes int
1dba0 6f 20 2a 70 70 53 74 6d 74 20 61 20 70 6f 69 6e  o *ppStmt a poin
1dbb0 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20  ter to a new.** 
1dbc0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
1dbd0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72  ed statement] or
1dbe0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55   a pointer to NU
1dbf0 4c 4c 20 69 66 20 7a 53 71 6c 20 63 6f 6e 74 61  LL if zSql conta
1dc00 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ins.**          
1dc10 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  nothing other th
1dc20 61 6e 20 77 68 69 74 65 73 70 61 63 65 20 6f 72  an whitespace or
1dc30 20 63 6f 6d 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a   comments..**.**
1dc40 20 7b 46 31 33 30 31 39 7d 20 54 68 65 20 5b 73   {F13019} The [s
1dc50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1dc60 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
1dc70 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  nd its variants 
1dc80 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
1dc90 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f     [SQLITE_OK] o
1dca0 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  r an appropriate
1dcb0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70   [error code] up
1dcc0 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a  on failure..**.*
1dcd0 2a 20 7b 46 31 33 30 32 31 7d 20 42 65 66 6f 72  * {F13021} Befor
1dce0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
1dcf0 72 65 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65  re(db,zSql,nByte
1dd00 2c 70 70 53 74 6d 74 2c 70 7a 54 61 69 6c 29 5d  ,ppStmt,pzTail)]
1dd10 20 6f 72 20 69 74 73 0a 2a 2a 20 20 20 20 20 20   or its.**      
1dd20 20 20 20 20 76 61 72 69 61 6e 74 73 20 72 65 74      variants ret
1dd30 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 20 28 61  urns an error (a
1dd40 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
1dd50 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 29  han [SQLITE_OK])
1dd60 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
1dd70 65 79 20 66 69 72 73 74 20 73 65 74 20 2a 70 70  ey first set *pp
1dd80 53 74 6d 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  Stmt to NULL..*/
1dd90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
1dda0 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20  pare(.  sqlite3 
1ddb0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1ddc0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
1ddd0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1dde0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
1ddf0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
1de00 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
1de10 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1de20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1de30 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1de40 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1de50 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1de60 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1de70 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1de80 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1de90 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
1dea0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1deb0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1dec0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1ded0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1dee0 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71  prepare_v2(.  sq
1def0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1df00 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1df10 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1df20 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
1df30 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1df40 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
1df50 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1df60 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1df70 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1df80 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1df90 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1dfa0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1dfb0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1dfc0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1dfd0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
1dfe0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1dff0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1e000 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1e010 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
1e020 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1e030 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1e040 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1e050 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
1e060 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
1e070 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
1e080 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
1e090 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
1e0a0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1e0b0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1e0c0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1e0d0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1e0e0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1e0f0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1e100 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1e110 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
1e120 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
1e130 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1e140 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1e150 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1e160 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1e170 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69  are16_v2(.  sqli
1e180 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1e190 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1e1a0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1e1b0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
1e1c0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1e1d0 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
1e1e0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
1e1f0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
1e200 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
1e210 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
1e220 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
1e230 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
1e240 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
1e250 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
1e260 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
1e270 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
1e280 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
1e290 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
1e2a0 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ql */.);../*.** 
1e2b0 43 41 50 49 52 45 46 3a 20 52 65 74 72 69 65 76  CAPIREF: Retriev
1e2c0 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
1e2d0 4c 20 7b 46 31 33 31 30 30 7d 0a 2a 2a 0a 2a 2a  L {F13100}.**.**
1e2e0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1e2f0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
1e300 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20  etrieve a saved 
1e310 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67  copy of the orig
1e320 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74  inal.** SQL text
1e330 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
1e340 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1e350 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73  ement] if that s
1e360 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
1e370 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
1e380 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
1e390 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1e3a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e3b0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
1e3c0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1e3d0 2a 20 7b 46 31 33 31 30 31 7d 20 49 66 20 74 68  * {F13101} If th
1e3e0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
1e3f0 65 6d 65 6e 74 5d 20 70 61 73 73 65 64 20 61 73  ement] passed as
1e400 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
1e410 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1e420 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 77 61 73  lite3_sql()] was
1e430 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
1e440 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
1e450 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1e460 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1e470 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1e480 76 32 28 29 5d 2c 20 74 68 65 6e 20 5b 73 71 6c  v2()], then [sql
1e490 69 74 65 33 5f 73 71 6c 28 29 5d 20 72 65 74 75  ite3_sql()] retu
1e4a0 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
1e4b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
1e4c0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1e4d0 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
1e4e0 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
1e4f0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ng.**          o
1e500 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 53  f the original S
1e510 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
1e520 0a 2a 2a 20 7b 46 31 33 31 30 32 7d 20 49 66 20  .** {F13102} If 
1e530 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
1e540 61 74 65 6d 65 6e 74 5d 20 70 61 73 73 65 64 20  atement] passed 
1e550 61 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  as the argument 
1e560 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
1e570 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 77  sqlite3_sql()] w
1e580 61 73 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e  as compiled usin
1e590 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
1e5a0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a  3_prepare()] or.
1e5b0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1e5c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1e5d0 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ], then [sqlite3
1e5e0 5f 73 71 6c 28 29 5d 20 72 65 74 75 72 6e 73 20  _sql()] returns 
1e5f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1e600 2a 2a 0a 2a 2a 20 7b 46 31 33 31 30 33 7d 20 54  **.** {F13103} T
1e610 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e  he string return
1e620 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  ed by [sqlite3_s
1e630 71 6c 28 53 29 5d 20 69 73 20 76 61 6c 69 64 20  ql(S)] is valid 
1e640 75 6e 74 69 6c 20 74 68 65 0a 2a 2a 20 20 20 20  until the.**    
1e650 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
1e660 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20  statement] S is 
1e670 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 5b 73  deleted using [s
1e680 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1e690 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  S)]..*/.const ch
1e6a0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
1e6b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
1e6c0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
1e6d0 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c  I3REF: Dynamical
1e6e0 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f  ly Typed Value O
1e6f0 62 6a 65 63 74 20 7b 46 31 35 30 30 30 7d 0a 2a  bject {F15000}.*
1e700 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
1e710 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1e720 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
1e730 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1e740 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
1e750 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
1e760 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
1e770 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
1e780 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
1e790 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
1e7a0 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
1e7b0 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
1e7c0 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
1e7d0 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
1e7e0 73 74 6f 72 65 73 2e 20 56 61 6c 75 65 73 20 73  stores. Values s
1e7f0 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33  tored in sqlite3
1e800 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a  _value objects.*
1e810 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72  * can be integer
1e820 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
1e830 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
1e840 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
1e850 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69  L..**.** An sqli
1e860 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1e870 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22   may be either "
1e880 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75  protected" or "u
1e890 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20  nprotected"..** 
1e8a0 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  Some interfaces 
1e8b0 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63  require a protec
1e8c0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1e8d0 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66  e.  Other interf
1e8e0 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63  aces.** will acc
1e8f0 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f  ept either a pro
1e900 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70  tected or an unp
1e910 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1e920 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79  _value..** Every
1e930 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
1e940 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f  accepts sqlite3_
1e950 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20  value arguments 
1e960 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65  specifies.** whe
1e970 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72  ther or not it r
1e980 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63  equires a protec
1e990 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1e9a0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
1e9b0 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
1e9c0 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
1e9d0 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
1e9e0 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
1e9f0 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20  tex is held.  A 
1ea00 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
1ea10 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
1ea20 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
1ea30 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
1ea40 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
1ea50 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
1ea60 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
1ea70 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
1ea80 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
1ea90 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
1eaa0 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
1eab0 28 77 69 74 68 20 53 51 4c 49 54 45 5f 54 48 52  (with SQLITE_THR
1eac0 45 41 44 53 41 46 45 3d 30 20 61 6e 64 20 77 69  EADSAFE=0 and wi
1ead0 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  th [sqlite3_thre
1eae0 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e  adsafe()] return
1eaf0 69 6e 67 20 30 29 0a 2a 2a 20 74 68 65 6e 20 74  ing 0).** then t
1eb00 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69  here is no disti
1eb10 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
1eb20 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
1eb30 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
1eb40 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1eb50 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62  s and they can b
1eb60 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  e used interchan
1eb70 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72  geably.  However
1eb80 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ,.** for maximum
1eb90 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
1eba0 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  y it is recommen
1ebb0 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
1ebc0 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d  tions.** still m
1ebd0 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
1ebe0 69 6f 6e 20 62 65 74 77 65 65 6e 20 62 65 74 77  ion between betw
1ebf0 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
1ec00 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
1ec10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1ec20 62 6a 65 63 74 73 20 65 76 65 6e 20 69 66 20 74  bjects even if t
1ec30 68 65 79 20 61 72 65 20 73 69 6e 67 6c 65 20 74  hey are single t
1ec40 68 72 65 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  hreaded..**.** T
1ec50 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
1ec60 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72   objects that ar
1ec70 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61  e passed as para
1ec80 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a  meters into the.
1ec90 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
1eca0 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f  n of [applicatio
1ecb0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
1ecc0 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f  nctions] are pro
1ecd0 74 65 63 74 65 64 2e 0a 2a 2a 20 54 68 65 20 73  tected..** The s
1ece0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1ecf0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
1ed00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
1ed10 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
1ed20 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
1ed30 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
1ed40 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1ed50 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
1ed60 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
1ed70 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
1ed80 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1ed90 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
1eda0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
1edb0 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
1edc0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
1edd0 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
1ede0 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
1edf0 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
1ee00 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1ee10 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
1ee20 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
1ee30 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
1ee40 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
1ee50 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
1ee60 6a 65 63 74 20 7b 46 31 36 30 30 31 7d 0a 2a 2a  ject {F16001}.**
1ee70 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
1ee80 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
1ee90 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
1eea0 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
1eeb0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
1eec0 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20  text object.  A 
1eed0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71  pointer to an sq
1eee0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
1eef0 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79  ject.** is alway
1ef00 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
1ef10 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f  r to [applicatio
1ef20 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
1ef30 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65  nctions]..** The
1ef40 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
1ef50 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
1ef60 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
1ef70 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a   will pass this.
1ef80 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75  ** pointer throu
1ef90 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f  gh into calls to
1efa0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
1efb0 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72  _int | sqlite3_r
1efc0 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  esult()],.** [sq
1efd0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
1efe0 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c  context()], [sql
1eff0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
1f000 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ],.** [sqlite3_c
1f010 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
1f020 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65  ()], [sqlite3_ge
1f030 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a  t_auxdata()],.**
1f040 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33   and/or [sqlite3
1f050 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e  _set_auxdata()].
1f060 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
1f070 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ct sqlite3_conte
1f080 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt sqlite3_conte
1f090 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  xt;../*.** CAPI3
1f0a0 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c  REF: Binding Val
1f0b0 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20  ues To Prepared 
1f0c0 53 74 61 74 65 6d 65 6e 74 73 20 7b 46 31 33 35  Statements {F135
1f0d0 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00}.** KEYWORDS:
1f0e0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
1f0f0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
1f100 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  rs} {host parame
1f110 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59  ter name}.** KEY
1f120 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61  WORDS: {SQL para
1f130 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61  meter} {SQL para
1f140 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74  meters} {paramet
1f150 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a  er binding}.**.*
1f160 2a 20 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72  * In the SQL str
1f170 69 6e 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73  ings input to [s
1f180 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1f190 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  2()] and its var
1f1a0 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61  iants,.** litera
1f1b0 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63  ls may be replac
1f1c0 65 64 20 62 79 20 61 20 70 61 72 61 6d 65 74 65  ed by a paramete
1f1d0 72 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73  r in one of thes
1f1e0 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c  e forms:.**.** <
1f1f0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
1f200 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
1f210 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
1f220 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
1f230 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
1f240 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72  **.** In the par
1f250 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f  ameter forms sho
1f260 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20  wn above NNN is 
1f270 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
1f280 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 69  al,.** and VVV i
1f290 73 20 61 6e 20 61 6c 70 68 61 2d 6e 75 6d 65 72  s an alpha-numer
1f2a0 69 63 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  ic parameter nam
1f2b0 65 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66  e. The values of
1f2c0 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
1f2d0 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
1f2e0 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
1f2f0 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
1f300 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
1f310 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
1f320 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
1f330 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
1f340 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
1f350 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
1f360 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
1f370 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
1f380 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
1f390 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
1f3a0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
1f3b0 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
1f3c0 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
1f3d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1f3e0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1f3f0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nts..**.** The s
1f400 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
1f410 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
1f420 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
1f430 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54   to be set..** T
1f440 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20  he leftmost SQL 
1f450 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
1f460 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 57 68   index of 1.  Wh
1f470 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
1f480 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
1f490 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
1f4a0 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
1f4b0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
1f4c0 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
1f4d0 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
1f4e0 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
1f4f0 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
1f500 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61  The index for na
1f510 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
1f520 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
1f530 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
1f540 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1f550 65 74 65 72 5f 6e 61 6d 65 28 29 5d 20 41 50 49  eter_name()] API
1f560 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 54 68   if desired.  Th
1f570 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
1f580 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
1f590 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
1f5a0 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e   NNN..** The NNN
1f5b0 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
1f5c0 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
1f5d0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
1f5e0 20 70 61 72 61 6d 65 74 65 72 20 53 51 4c 49 54   parameter SQLIT
1f5f0 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e  E_MAX_VARIABLE_N
1f600 55 4d 42 45 52 20 28 64 65 66 61 75 6c 74 20 76  UMBER (default v
1f610 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
1f620 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75  * The third argu
1f630 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
1f640 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
1f650 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1f660 2a 20 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  * In those routi
1f670 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
1f680 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
1f690 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
1f6a0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
1f6b0 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
1f6c0 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
1f6d0 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
1f6e0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
1f6f0 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
1f700 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
1f710 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
1f720 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 49  characters..** I
1f730 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
1f740 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69  ameter is negati
1f750 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  ve, the length o
1f760 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
1f770 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
1f780 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
1f790 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
1f7a0 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  inator..**.** Th
1f7b0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
1f7c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
1f7d0 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
1f7e0 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e  _bind_text(), an
1f7f0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  d.** sqlite3_bin
1f800 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20  d_text16() is a 
1f810 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
1f820 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
1f830 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
1f840 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
1f850 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
1f860 74 68 20 69 74 2e 20 49 66 20 74 68 65 20 66 69  th it. If the fi
1f870 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
1f880 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
1f890 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
1f8a0 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
1f8b0 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
1f8c0 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
1f8d0 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
1f8e0 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
1f8f0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
1f900 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
1f910 2a 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61  * If the fifth a
1f920 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20  rgument has the 
1f930 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52  value [SQLITE_TR
1f940 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a  ANSIENT], then.*
1f950 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69  * SQLite makes i
1f960 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
1f970 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20  opy of the data 
1f980 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
1f990 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  ore.** the sqlit
1f9a0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
1f9b0 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  ine returns..**.
1f9c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
1f9d0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
1f9e0 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
1f9f0 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20  LOB of length N 
1fa00 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
1fa10 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20  d with zeroes.  
1fa20 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
1fa30 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
1fa40 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
1fa50 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
1fa60 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77  hold its size) w
1fa70 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
1fa80 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
1fa90 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
1faa0 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
1fab0 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  s placeholders f
1fac0 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
1fad0 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
1fae0 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
1faf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
1fb00 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
1fb10 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ntal BLOB I/O] r
1fb20 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65  outines..** A ne
1fb30 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
1fb40 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
1fb50 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
1fb60 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
1fb70 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
1fb80 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
1fb90 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
1fba0 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  after.** [sqlite
1fbb0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1fbc0 28 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74  (and its variant
1fbd0 73 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  s) or [sqlite3_r
1fbe0 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62  eset()] and.** b
1fbf0 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73  efore [sqlite3_s
1fc00 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69  tep()]..** Bindi
1fc10 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
1fc20 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
1fc30 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
1fc40 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64  tine..** Unbound
1fc50 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
1fc60 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
1fc70 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ULL..**.** These
1fc80 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1fc90 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
1fca0 73 75 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72  success or an er
1fcb0 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61  ror code if.** a
1fcc0 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
1fcd0 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e  ng.  [SQLITE_RAN
1fce0 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
1fcf0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1fd00 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
1fd10 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c   of range.  [SQL
1fd20 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
1fd30 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
1fd40 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51  () fails..** [SQ
1fd50 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 69 67  LITE_MISUSE] mig
1fd60 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69  ht be returned i
1fd70 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1fd80 20 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61   are called on a
1fd90 0a 2a 2a 20 76 69 72 74 75 61 6c 20 6d 61 63 68  .** virtual mach
1fda0 69 6e 65 20 74 68 61 74 20 69 73 20 74 68 65 20  ine that is the 
1fdb0 77 72 6f 6e 67 20 73 74 61 74 65 20 6f 72 20 77  wrong state or w
1fdc0 68 69 63 68 20 68 61 73 20 61 6c 72 65 61 64 79  hich has already
1fdd0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e   been finalized.
1fde0 0a 2a 2a 20 44 65 74 65 63 74 69 6f 6e 20 6f 66  .** Detection of
1fdf0 20 6d 69 73 75 73 65 20 69 73 20 75 6e 72 65 6c   misuse is unrel
1fe00 69 61 62 6c 65 2e 20 20 41 70 70 6c 69 63 61 74  iable.  Applicat
1fe10 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ions should not 
1fe20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c  depend.** on SQL
1fe30 49 54 45 5f 4d 49 53 55 53 45 20 72 65 74 75 72  ITE_MISUSE retur
1fe40 6e 73 2e 20 20 53 51 4c 49 54 45 5f 4d 49 53 55  ns.  SQLITE_MISU
1fe50 53 45 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  SE is intended t
1fe60 6f 20 69 6e 64 69 63 61 74 65 20 61 0a 2a 2a 20  o indicate a.** 
1fe70 61 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e  a logic error in
1fe80 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1fe90 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
1fea0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
1feb0 68 74 0a 2a 2a 20 70 61 6e 69 63 20 72 61 74 68  ht.** panic rath
1fec0 65 72 20 74 68 61 6e 20 72 65 74 75 72 6e 20 53  er than return S
1fed0 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
1fee0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
1fef0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1ff00 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
1ff10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1ff20 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
1ff30 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
1ff40 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1ff50 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  index()]..**.** 
1ff60 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1ff70 2a 20 7b 46 31 33 35 30 36 7d 20 54 68 65 20 5b  * {F13506} The [
1ff80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
1ff90 6d 70 69 6c 65 72 5d 20 72 65 63 6f 67 6e 69 7a  mpiler] recogniz
1ffa0 65 73 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65  es tokens of the
1ffb0 20 66 6f 72 6d 73 0a 2a 2a 20 20 20 20 20 20 20   forms.**       
1ffc0 20 20 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20     "?", "?NNN", 
1ffd0 22 24 56 56 56 22 2c 20 22 3a 56 56 56 22 2c 20  "$VVV", ":VVV", 
1ffe0 61 6e 64 20 22 40 56 56 56 22 20 61 73 20 53 51  and "@VVV" as SQ
1fff0 4c 20 70 61 72 61 6d 65 74 65 72 73 2c 0a 2a 2a  L parameters,.**
20000 20 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20            where 
20010 4e 4e 4e 20 69 73 20 61 6e 79 20 73 65 71 75 65  NNN is any seque
20020 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  nce of one or mo
20030 72 65 20 64 69 67 69 74 73 0a 2a 2a 20 20 20 20  re digits.**    
20040 20 20 20 20 20 20 61 6e 64 20 77 68 65 72 65 20        and where 
20050 56 56 56 20 69 73 20 61 6e 79 20 73 65 71 75 65  VVV is any seque
20060 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  nce of one or mo
20070 72 65 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 0a  re alphanumeric.
20080 2a 2a 20 20 20 20 20 20 20 20 20 20 63 68 61 72  **          char
20090 61 63 74 65 72 73 20 6f 72 20 22 3a 3a 22 20 6f  acters or "::" o
200a0 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77  ptionally follow
200b0 65 64 20 62 79 20 61 20 73 74 72 69 6e 67 20 63  ed by a string c
200c0 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20  ontaining.**    
200d0 20 20 20 20 20 20 6e 6f 20 73 70 61 63 65 73 20        no spaces 
200e0 61 6e 64 20 63 6f 6e 74 61 69 6e 65 64 20 77 69  and contained wi
200f0 74 68 69 6e 20 70 61 72 65 6e 74 68 65 73 65 73  thin parentheses
20100 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 30 39 7d  ..**.** {F13509}
20110 20 54 68 65 20 69 6e 69 74 69 61 6c 20 76 61 6c   The initial val
20120 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ue of an SQL par
20130 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 2e 0a  ameter is NULL..
20140 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31 32 7d 20 54  **.** {F13512} T
20150 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22  he index of an "
20160 3f 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ?" SQL parameter
20170 20 69 73 20 6f 6e 65 20 6c 61 72 67 65 72 20 74   is one larger t
20180 68 61 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  han the.**      
20190 20 20 20 20 6c 61 72 67 65 73 74 20 69 6e 64 65      largest inde
201a0 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74  x of SQL paramet
201b0 65 72 20 74 6f 20 74 68 65 20 6c 65 66 74 2c 20  er to the left, 
201c0 6f 72 20 31 20 69 66 0a 2a 2a 20 20 20 20 20 20  or 1 if.**      
201d0 20 20 20 20 74 68 65 20 22 3f 22 20 69 73 20 74      the "?" is t
201e0 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20  he leftmost SQL 
201f0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
20200 20 7b 46 31 33 35 31 35 7d 20 54 68 65 20 69 6e   {F13515} The in
20210 64 65 78 20 6f 66 20 61 6e 20 22 3f 4e 4e 4e 22  dex of an "?NNN"
20220 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
20230 73 20 74 68 65 20 69 6e 74 65 67 65 72 20 4e 4e  s the integer NN
20240 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 35 31 38  N..**.** {F13518
20250 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61  } The index of a
20260 6e 20 22 3a 56 56 56 22 2c 20 22 24 56 56 56 22  n ":VVV", "$VVV"
20270 2c 20 6f 72 20 22 40 56 56 56 22 20 53 51 4c 20  , or "@VVV" SQL 
20280 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
20290 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d           the sam
202a0 65 20 61 73 20 74 68 65 20 69 6e 64 65 78 20 6f  e as the index o
202b0 66 20 6c 65 66 74 6d 6f 73 74 20 6f 63 63 75 72  f leftmost occur
202c0 72 65 6e 63 65 73 20 6f 66 20 74 68 65 20 73 61  rences of the sa
202d0 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  me.**          p
202e0 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 6f 6e 65  arameter, or one
202f0 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 65 20 6c   more than the l
20300 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 76 65  argest index ove
20310 72 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  r all.**        
20320 20 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20    parameters to 
20330 74 68 65 20 6c 65 66 74 20 69 66 20 74 68 69 73  the left if this
20340 20 69 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   is the first oc
20350 63 75 72 72 65 6e 63 65 0a 2a 2a 20 20 20 20 20  currence.**     
20360 20 20 20 20 20 6f 66 20 74 68 69 73 20 70 61 72       of this par
20370 61 6d 65 74 65 72 2c 20 6f 72 20 31 20 69 66 20  ameter, or 1 if 
20380 74 68 69 73 20 69 73 20 74 68 65 20 6c 65 66 74  this is the left
20390 6d 6f 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  most parameter..
203a0 2a 2a 0a 2a 2a 20 7b 46 31 33 35 32 31 7d 20 54  **.** {F13521} T
203b0 68 65 20 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e  he [SQL statemen
203c0 74 20 63 6f 6d 70 69 6c 65 72 5d 20 66 61 69 6c  t compiler] fail
203d0 73 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54  s with an [SQLIT
203e0 45 5f 52 41 4e 47 45 5d 0a 2a 2a 20 20 20 20 20  E_RANGE].**     
203f0 20 20 20 20 20 65 72 72 6f 72 20 69 66 20 74 68       error if th
20400 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51  e index of an SQ
20410 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c  L parameter is l
20420 65 73 73 20 74 68 61 6e 20 31 0a 2a 2a 20 20 20  ess than 1.**   
20430 20 20 20 20 20 20 20 6f 72 20 67 72 65 61 74 65         or greate
20440 72 20 74 68 61 6e 20 74 68 65 20 63 6f 6d 70 69  r than the compi
20450 6c 65 2d 74 69 6d 65 20 53 51 4c 49 54 45 5f 4d  le-time SQLITE_M
20460 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  AX_VARIABLE_NUMB
20470 45 52 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  ER.**          p
20480 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
20490 7b 46 31 33 35 32 34 7d 20 43 61 6c 6c 73 20 74  {F13524} Calls t
204a0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
204b0 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62  text | sqlite3_b
204c0 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e 2e 29 5d 0a  ind(S,N,V,...)].
204d0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 6f  **          asso
204e0 63 69 61 74 65 20 74 68 65 20 76 61 6c 75 65 20  ciate the value 
204f0 56 20 77 69 74 68 20 61 6c 6c 20 53 51 4c 20 70  V with all SQL p
20500 61 72 61 6d 65 74 65 72 73 20 68 61 76 69 6e 67  arameters having
20510 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
20520 69 6e 64 65 78 20 6f 66 20 4e 20 69 6e 20 74 68  index of N in th
20530 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
20540 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20  ement] S..**.** 
20550 7b 46 31 33 35 32 37 7d 20 43 61 6c 6c 73 20 74  {F13527} Calls t
20560 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
20570 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62  text | sqlite3_b
20580 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a  ind(S,N,...)].**
20590 20 20 20 20 20 20 20 20 20 20 6f 76 65 72 72 69            overri
205a0 64 65 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 77  de prior calls w
205b0 69 74 68 20 74 68 65 20 73 61 6d 65 20 76 61 6c  ith the same val
205c0 75 65 73 20 6f 66 20 53 20 61 6e 64 20 4e 2e 0a  ues of S and N..
205d0 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 30 7d 20 42  **.** {F13530} B
205e0 69 6e 64 69 6e 67 73 20 65 73 74 61 62 6c 69 73  indings establis
205f0 68 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  hed by [sqlite3_
20600 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69  bind_text | sqli
20610 74 65 33 5f 62 69 6e 64 28 53 2c 2e 2e 2e 29 5d  te3_bind(S,...)]
20620 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 65 72  .**          per
20630 73 69 73 74 20 61 63 72 6f 73 73 20 63 61 6c 6c  sist across call
20640 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
20650 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  set(S)]..**.** {
20660 46 31 33 35 33 33 7d 20 49 6e 20 63 61 6c 6c 73  F13533} In calls
20670 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
20680 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44  d_blob(S,N,V,L,D
20690 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
206a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
206b0 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20  xt(S,N,V,L,D)], 
206c0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
206d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
206e0 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20  t16(S,N,V,L,D)] 
206f0 53 51 4c 69 74 65 20 62 69 6e 64 73 20 74 68 65  SQLite binds the
20700 20 66 69 72 73 74 20 4c 0a 2a 2a 20 20 20 20 20   first L.**     
20710 20 20 20 20 20 62 79 74 65 73 20 6f 66 20 74 68       bytes of th
20720 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  e BLOB or string
20730 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56   pointed to by V
20740 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20 20 20 20 20  , when L.**     
20750 20 20 20 20 20 69 73 20 6e 6f 6e 2d 6e 65 67 61       is non-nega
20760 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  tive..**.** {F13
20770 35 33 36 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  536} In calls to
20780 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
20790 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20  ext(S,N,V,L,D)] 
207a0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
207b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
207c0 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20  t16(S,N,V,L,D)] 
207d0 53 51 4c 69 74 65 20 62 69 6e 64 73 20 63 68 61  SQLite binds cha
207e0 72 61 63 74 65 72 73 0a 2a 2a 20 20 20 20 20 20  racters.**      
207f0 20 20 20 20 66 72 6f 6d 20 56 20 74 68 72 6f 75      from V throu
20800 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
20810 6f 20 63 68 61 72 61 63 74 65 72 20 77 68 65 6e  o character when
20820 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a   L is negative..
20830 2a 2a 0a 2a 2a 20 7b 46 31 33 35 33 39 7d 20 49  **.** {F13539} I
20840 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
20850 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c  te3_bind_blob(S,
20860 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20  N,V,L,D)],.**   
20870 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
20880 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c  bind_text(S,N,V,
20890 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  L,D)], or.**    
208a0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
208b0 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56  ind_text16(S,N,V
208c0 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73  ,L,D)] when D is
208d0 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20   the special.** 
208e0 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 61 6e           constan
208f0 74 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  t [SQLITE_STATIC
20900 5d 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  ], SQLite assume
20910 73 20 74 68 61 74 20 74 68 65 20 76 61 6c 75 65  s that the value
20920 20 56 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69   V.**          i
20930 73 20 68 65 6c 64 20 69 6e 20 73 74 61 74 69 63  s held in static
20940 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65   unmanaged space
20950 20 74 68 61 74 20 77 69 6c 6c 20 6e 6f 74 20 63   that will not c
20960 68 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  hange.**        
20970 20 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66    during the lif
20980 65 74 69 6d 65 20 6f 66 20 74 68 65 20 62 69 6e  etime of the bin
20990 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33  ding..**.** {F13
209a0 35 34 32 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  542} In calls to
209b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
209c0 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c  lob(S,N,V,L,D)],
209d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
209e0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
209f0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a  S,N,V,L,D)], or.
20a00 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
20a10 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
20a20 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65  (S,N,V,L,D)] whe
20a30 6e 20 44 20 69 73 20 74 68 65 20 73 70 65 63 69  n D is the speci
20a40 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  al.**          c
20a50 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f  onstant [SQLITE_
20a60 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 20  TRANSIENT], the 
20a70 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73 20 61 0a  routine makes a.
20a80 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 69 76  **          priv
20a90 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
20aa0 76 61 6c 75 65 20 56 20 62 65 66 6f 72 65 20 69  value V before i
20ab0 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
20ac0 20 7b 46 31 33 35 34 35 7d 20 49 6e 20 63 61 6c   {F13545} In cal
20ad0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
20ae0 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c  ind_blob(S,N,V,L
20af0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
20b00 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
20b10 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  text(S,N,V,L,D)]
20b20 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
20b30 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
20b40 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
20b50 5d 20 77 68 65 6e 20 44 20 69 73 20 61 20 70 6f  ] when D is a po
20b60 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20  inter to.**     
20b70 20 20 20 20 20 61 20 66 75 6e 63 74 69 6f 6e 2c       a function,
20b80 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
20b90 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 74 6f  that function to
20ba0 20 64 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20   destroy the.** 
20bb0 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 56           value V
20bc0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
20bd0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65  nished using the
20be0 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20   value V..**.** 
20bf0 7b 46 31 33 35 34 38 7d 20 49 6e 20 63 61 6c 6c  {F13548} In call
20c00 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
20c10 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 53 2c 4e 2c  nd_zeroblob(S,N,
20c20 56 2c 4c 29 5d 20 74 68 65 20 76 61 6c 75 65 20  V,L)] the value 
20c30 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  bound.**        
20c40 20 20 69 73 20 61 20 42 4c 4f 42 20 6f 66 20 4c    is a BLOB of L
20c50 20 62 79 74 65 73 2c 20 6f 72 20 61 20 7a 65 72   bytes, or a zer
20c60 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 66  o-length BLOB if
20c70 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a   L is negative..
20c80 2a 2a 0a 2a 2a 20 7b 46 31 33 35 35 31 7d 20 49  **.** {F13551} I
20c90 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
20ca0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 53  te3_bind_value(S
20cb0 2c 4e 2c 56 29 5d 20 74 68 65 20 56 20 61 72 67  ,N,V)] the V arg
20cc0 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20 20 20 20  ument may.**    
20cd0 20 20 20 20 20 20 62 65 20 65 69 74 68 65 72 20        be either 
20ce0 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  a [protected sql
20cf0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
20d00 63 74 20 6f 72 20 61 6e 0a 2a 2a 20 20 20 20 20  ct or an.**     
20d10 20 20 20 20 20 5b 75 6e 70 72 6f 74 65 63 74 65       [unprotecte
20d20 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
20d30 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20   object..*/.int 
20d40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
20d50 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
20d60 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
20d70 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
20d80 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
20d90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
20da0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
20db0 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
20dc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
20dd0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
20de0 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
20df0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
20e00 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
20e10 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
20e20 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
20e30 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
20e40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
20e50 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
20e60 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
20e70 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
20e80 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
20e90 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
20ea0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
20eb0 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
20ec0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
20ed0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
20ee0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
20ef0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
20f00 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
20f10 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
20f20 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
20f30 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
20f40 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
20f50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
20f60 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
20f70 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
20f80 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
20f90 74 65 72 73 20 7b 46 31 33 36 30 30 7d 0a 2a 2a  ters {F13600}.**
20fa0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
20fb0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
20fc0 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
20fd0 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
20fe0 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
20ff0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
21000 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
21010 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
21020 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
21030 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
21040 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
21050 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
21060 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
21070 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
21080 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
21090 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
210a0 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
210b0 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
210c0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   time..**.** Thi
210d0 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
210e0 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
210f0 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
21100 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
21110 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
21120 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
21130 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
21140 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
21150 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
21160 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
21170 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
21180 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
21190 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
211a0 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
211b0 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a  n the list..**.*
211c0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
211d0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
211e0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
211f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
21200 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
21210 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
21220 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
21230 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
21240 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
21250 2a 0a 2a 2a 20 7b 46 31 33 36 30 31 7d 20 54 68  *.** {F13601} Th
21260 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
21270 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
21280 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
21290 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
212a0 20 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e    the largest in
212b0 64 65 78 20 6f 66 20 61 6c 6c 20 53 51 4c 20 70  dex of all SQL p
212c0 61 72 61 6d 65 74 65 72 73 20 69 6e 20 74 68 65  arameters in the
212d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
212e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
212f0 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53 20 63  ] S, or 0 if S c
21300 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70  ontains no SQL p
21310 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e  arameters..*/.in
21320 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
21330 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
21340 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
21350 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21360 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
21370 61 72 61 6d 65 74 65 72 20 7b 46 31 33 36 32 30  arameter {F13620
21380 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
21390 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
213a0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61  ointer to the na
213b0 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a  me of the n-th.*
213c0 2a 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  * [SQL parameter
213d0 5d 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] in a [prepared
213e0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
213f0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
21400 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
21410 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
21420 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
21430 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
21440 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
21450 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
21460 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
21470 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
21480 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
21490 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
214a0 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
214b0 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
214c0 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
214d0 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
214e0 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65  ame..** Paramete
214f0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
21500 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
21510 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
21520 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
21530 6e 64 20 61 72 65 20 61 6c 73 6f 20 72 65 66 65  nd are also refe
21540 72 72 65 64 20 74 6f 20 61 73 20 22 61 6e 6f 6e  rred to as "anon
21550 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73  ymous parameters
21560 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  "..**.** The fir
21570 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
21580 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
21590 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
215a0 2a 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e  * If the value n
215b0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
215c0 20 6f 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20   or if the n-th 
215d0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
215e0 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
215f0 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
21600 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73    The returned s
21610 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61  tring is.** alwa
21620 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f  ys in UTF-8 enco
21630 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ding even if the
21640 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
21650 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   was.** original
21660 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ly specified as 
21670 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74  UTF-16 in [sqlit
21680 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
21690 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  or.** [sqlite3_p
216a0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
216b0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
216c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
216d0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
216e0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
216f0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
21700 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
21710 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
21720 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
21730 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
21740 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36 32  TS:.**.** {F1362
21750 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
21760 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
21770 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ame(S,N)] interf
21780 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ace returns.**  
21790 20 20 20 20 20 20 20 20 61 20 55 54 46 2d 38 20          a UTF-8 
217a0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
217b0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
217c0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a   parameter in.**
217d0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70            the [p
217e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
217f0 74 5d 20 53 20 68 61 76 69 6e 67 20 69 6e 64 65  t] S having inde
21800 78 20 4e 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  x N, or.**      
21810 20 20 20 20 4e 55 4c 4c 20 69 66 20 74 68 65 72      NULL if ther
21820 65 20 69 73 20 6e 6f 20 53 51 4c 20 70 61 72 61  e is no SQL para
21830 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64 65 78  meter with index
21840 20 4e 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20   N or if the.** 
21850 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74           paramet
21860 65 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20  er with index N 
21870 69 73 20 61 6e 20 61 6e 6f 6e 79 6d 6f 75 73 20  is an anonymous 
21880 70 61 72 61 6d 65 74 65 72 20 22 3f 22 2e 0a 2a  parameter "?"..*
21890 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
218a0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
218b0 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
218c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
218d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
218e0 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
218f0 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
21900 6e 20 4e 61 6d 65 20 7b 46 31 33 36 34 30 7d 0a  n Name {F13640}.
21910 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65  **.** Return the
21920 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
21930 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
21940 20 69 74 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a   its name.  The.
21950 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
21960 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
21970 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
21980 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
21990 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
219a0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
219b0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41  ite3_bind()].  A
219c0 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75   zero.** is retu
219d0 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68  rned if no match
219e0 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  ing parameter is
219f0 20 66 6f 75 6e 64 2e 20 20 54 68 65 20 70 61 72   found.  The par
21a00 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d  ameter.** name m
21a10 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20  ust be given in 
21a20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68  UTF-8 even if th
21a30 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
21a40 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70  ment.** was prep
21a50 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36  ared from UTF-16
21a60 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c   text using [sql
21a70 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
21a80 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
21a90 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
21aa0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
21ab0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
21ac0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
21ad0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
21ae0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
21af0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
21b00 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  dex()]..**.** IN
21b10 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
21b20 7b 46 31 33 36 34 31 7d 20 54 68 65 20 5b 73 71  {F13641} The [sq
21b30 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
21b40 65 74 65 72 5f 69 6e 64 65 78 28 53 2c 4e 29 5d  eter_index(S,N)]
21b50 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
21b60 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ns.**          t
21b70 68 65 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20  he index of SQL 
21b80 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
21b90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
21ba0 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ment].**        
21bb0 20 20 53 20 77 68 6f 73 65 20 6e 61 6d 65 20 6d    S whose name m
21bc0 61 74 63 68 65 73 20 74 68 65 20 55 54 46 2d 38  atches the UTF-8
21bd0 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20 30 20   string N, or 0 
21be0 69 66 20 74 68 65 72 65 20 69 73 0a 2a 2a 20 20  if there is.**  
21bf0 20 20 20 20 20 20 20 20 6e 6f 20 6d 61 74 63 68          no match
21c00 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
21c10 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
21c20 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
21c30 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
21c40 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
21c50 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
21c60 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
21c70 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
21c80 6d 65 6e 74 20 7b 46 31 33 36 36 30 7d 0a 2a 2a  ment {F13660}.**
21c90 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f 20  .** Contrary to 
21ca0 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
21cb0 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
21cc0 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
21cd0 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
21ce0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
21cf0 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
21d00 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
21d10 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 55 73 65 20  tement]..** Use 
21d20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
21d30 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
21d40 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
21d50 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  L..**.** INVARIA
21d60 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 36  NTS:.**.** {F136
21d70 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  61} The [sqlite3
21d80 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
21d90 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
21da0 73 65 74 73 20 61 6c 6c 20 53 51 4c 0a 2a 2a 20  sets all SQL.** 
21db0 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74           paramet
21dc0 65 72 20 62 69 6e 64 69 6e 67 73 20 69 6e 20 74  er bindings in t
21dd0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
21de0 74 65 6d 65 6e 74 5d 20 53 20 62 61 63 6b 20 74  tement] S back t
21df0 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
21e00 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
21e10 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
21e20 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
21e30 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
21e40 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
21e50 73 75 6c 74 20 53 65 74 20 7b 46 31 33 37 31 30  sult Set {F13710
21e60 7d 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74  }.**.** Return t
21e70 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
21e80 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
21e90 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
21ea0 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
21eb0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
21ec0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
21ed0 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20  urns 0 if pStmt 
21ee0 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61  is an SQL.** sta
21ef0 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73  tement that does
21f00 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61   not return data
21f10 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
21f20 20 55 50 44 41 54 45 29 2e 0a 2a 2a 0a 2a 2a 20   UPDATE)..**.** 
21f30 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
21f40 2a 20 7b 46 31 33 37 31 31 7d 20 54 68 65 20 5b  * {F13711} The [
21f50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
21f60 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72 66 61  ount(S)] interfa
21f70 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
21f80 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20  umber of.**     
21f90 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20 69 6e 20       columns in 
21fa0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 67  the result set g
21fb0 65 6e 65 72 61 74 65 64 20 62 79 20 74 68 65 20  enerated by the 
21fc0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
21fd0 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20 20 20 20  ent] S,.**      
21fe0 20 20 20 20 6f 72 20 30 20 69 66 20 53 20 64 6f      or 0 if S do
21ff0 65 73 20 6e 6f 74 20 67 65 6e 65 72 61 74 65 20  es not generate 
22000 61 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f  a result set..*/
22010 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
22020 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
22030 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
22040 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22050 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
22060 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 46   A Result Set {F
22070 31 33 37 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  13720}.**.** The
22080 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
22090 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
220a0 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
220b0 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
220c0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
220d0 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 61   of a SELECT sta
220e0 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c  tement.  The sql
220f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
22100 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
22110 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
22120 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
22130 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
22140 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  ing.** and sqlit
22150 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
22160 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
22170 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
22180 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
22190 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65  -16 string.  The
221a0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
221b0 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65   is the [prepare
221c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
221d0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
221e0 74 68 65 20 53 45 4c 45 43 54 20 73 74 61 74 65  the SELECT state
221f0 6d 65 6e 74 2e 20 54 68 65 20 73 65 63 6f 6e 64  ment. The second
22200 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
22210 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  e.** column numb
22220 65 72 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73  er.  The leftmos
22230 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
22240 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er 0..**.** The 
22250 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
22260 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
22270 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
22280 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
22290 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
222a0 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
222b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
222c0 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
222d0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
222e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
222f0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
22300 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
22310 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
22320 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65  .**.** If sqlite
22330 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
22340 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
22350 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
22360 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
22370 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
22380 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
22390 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
223a0 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
223b0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
223c0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
223d0 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c   name of a resul
223e0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
223f0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53  value of the "AS
22400 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20  " clause for.** 
22410 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20  that column, if 
22420 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63  there is an AS c
22430 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65  lause.  If there
22440 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65   is no AS clause
22450 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d  .** then the nam
22460 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e of the column 
22470 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  is unspecified a
22480 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  nd may change fr
22490 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73  om.** one releas
224a0 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74  e of SQLite to t
224b0 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 49  he next..**.** I
224c0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
224d0 20 7b 46 31 33 37 32 31 7d 20 41 20 73 75 63 63   {F13721} A succ
224e0 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
224f0 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
22500 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c  3_column_name(S,
22510 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  N)].**          
22520 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
22530 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
22540 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68  e Nth column (wh
22550 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20  ere 0 is.**     
22560 20 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73       the leftmos
22570 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68  t column) for th
22580 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
22590 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
225a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
225b0 65 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f  ent] S as a zero
225c0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
225d0 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
225e0 7b 46 31 33 37 32 33 7d 20 41 20 73 75 63 63 65  {F13723} A succe
225f0 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
22600 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
22610 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53  _column_name16(S
22620 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,N)].**         
22630 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
22640 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ns the name of t
22650 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77  he Nth column (w
22660 68 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20  here 0 is.**    
22670 20 20 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f        the leftmo
22680 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74  st column) for t
22690 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
226a0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
226b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
226c0 6d 65 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72  ment] S as a zer
226d0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
226e0 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20  -16 string.**   
226f0 20 20 20 20 20 20 20 69 6e 20 74 68 65 20 6e 61         in the na
22700 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
22710 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 34 7d 20  .**.** {F13724} 
22720 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
22730 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20  umn_name()] and 
22740 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
22750 6e 61 6d 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20  name16()].**    
22760 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
22770 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70   return a NULL p
22780 6f 69 6e 74 65 72 20 69 66 20 74 68 65 79 20 61  ointer if they a
22790 72 65 20 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20  re unable to.** 
227a0 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74           allocat
227b0 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  e memory to hold
227c0 20 74 68 65 69 72 20 6e 6f 72 6d 61 6c 20 72 65   their normal re
227d0 74 75 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  turn strings..**
227e0 0a 2a 2a 20 7b 46 31 33 37 32 35 7d 20 49 66 20  .** {F13725} If 
227f0 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
22800 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  to [sqlite3_colu
22810 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72  mn_name(S,N)] or
22820 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
22830 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
22840 65 31 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74  e16(S,N)] is out
22850 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 6e 20   of range, then 
22860 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
22870 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72  interfaces retur
22880 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
22890 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32 36 7d  ..**.** {F13726}
228a0 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
228b0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
228c0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c  3_column_name(S,
228d0 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  N)] and.**      
228e0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
228f0 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  umn_name16(S,N)]
22900 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
22910 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20   the next.**    
22920 20 20 20 20 20 20 63 61 6c 6c 20 74 6f 20 65 69        call to ei
22930 74 68 65 72 20 72 6f 75 74 69 6e 65 20 77 69 74  ther routine wit
22940 68 20 74 68 65 20 73 61 6d 65 20 53 20 61 6e 64  h the same S and
22950 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a   N parameters.**
22960 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74            or unt
22970 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  il [sqlite3_fina
22980 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c  lize(S)] is call
22990 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 32  ed..**.** {F1372
229a0 37 7d 20 57 68 65 6e 20 61 20 72 65 73 75 6c 74  7} When a result
229b0 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45   column of a [SE
229c0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
229d0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20  contains.**     
229e0 20 20 20 20 20 61 6e 20 41 53 20 63 6c 61 75 73       an AS claus
229f0 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  e, the name of t
22a00 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  hat column is th
22a10 65 20 69 64 65 6e 74 69 66 69 65 72 0a 2a 2a 20  e identifier.** 
22a20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20           to the 
22a30 72 69 67 68 74 20 6f 66 20 74 68 65 20 41 53 20  right of the AS 
22a40 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e 73  keyword..*/.cons
22a50 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
22a60 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
22a70 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
22a80 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
22a90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
22aa0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
22ab0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
22ac0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
22ad0 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
22ae0 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 46   Query Result {F
22af0 31 33 37 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  13740}.**.** The
22b00 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
22b10 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
22b20 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f  etermine what co
22b30 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20  lumn of what.** 
22b40 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64  table in which d
22b50 61 74 61 62 61 73 65 20 61 20 72 65 73 75 6c 74  atabase a result
22b60 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74 61   of a SELECT sta
22b70 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f  tement comes fro
22b80 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f  m..** The name o
22b90 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
22ba0 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
22bb0 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
22bc0 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
22bd0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
22be0 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64   string.  The _d
22bf0 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
22c00 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
22c10 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
22c20 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
22c30 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
22c40 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
22c50 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
22c60 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
22c70 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
22c80 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
22c90 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
22ca0 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
22cb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
22cc0 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
22cd0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
22ce0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
22cf0 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
22d00 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
22d10 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
22d20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
22d30 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ding..**.** The 
22d40 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
22d50 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
22d60 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
22d70 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
22d80 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
22d90 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  column..**.** Th
22da0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
22db0 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   to the followin
22dc0 67 20 63 61 6c 6c 73 20 69 73 20 61 20 5b 70 72  g calls is a [pr
22dd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22de0 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  ]..** These func
22df0 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
22e00 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
22e10 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
22e20 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65  turned by.** the
22e30 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72   statement, wher
22e40 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
22e50 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
22e60 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ent..**.** If th
22e70 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
22e80 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61  urned by the sta
22e90 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70  tement is an exp
22ea0 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75  ression or.** su
22eb0 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f  bquery and is no
22ec0 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  t a column value
22ed0 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68  , then all of th
22ee0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
22ef0 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54  turn.** NULL.  T
22f00 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67  hese routine mig
22f10 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e  ht also return N
22f20 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20  ULL if a memory 
22f30 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
22f40 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 4f 74 68  .** occurs.  Oth
22f50 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
22f60 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
22f70 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
22f80 61 62 61 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20  abase, table.** 
22f90 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  and column that 
22fa0 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
22fb0 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
22fc0 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73  d from..**.** As
22fd0 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
22fe0 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
22ff0 73 65 20 70 6f 73 74 66 69 78 65 64 20 77 69 74  se postfixed wit
23000 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
23010 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
23020 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68  strings, the oth
23030 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
23040 75 72 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d  urn UTF-8. {END}
23050 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49  .**.** These API
23060 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
23070 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
23080 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
23090 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
230a0 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
230b0 4e 5f 4d 45 54 41 44 41 54 41 20 70 72 65 70 72  N_METADATA prepr
230c0 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64  ocessor symbol d
230d0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 55  efined..**.** {U
230e0 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f  13751}.** If two
230f0 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
23100 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
23110 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
23120 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
23130 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
23140 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
23150 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
23160 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
23170 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
23180 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
23190 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
231a0 2a 20 7b 46 31 33 37 34 31 7d 20 54 68 65 20 5b  * {F13741} The [
231b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
231c0 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 53 2c 4e  atabase_name(S,N
231d0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
231e0 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
231f0 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d          the UTF-
23200 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
23210 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  d name of the da
23220 74 61 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63  tabase from whic
23230 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  h the.**        
23240 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c    Nth result col
23250 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70  umn of the [prep
23260 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
23270 53 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a  S is extracted,.
23280 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e  **          or N
23290 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63  ULL if the Nth c
232a0 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20  olumn of S is a 
232b0 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69  general expressi
232c0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  on.**          o
232d0 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
232e0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
232f0 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65  o store the name
23300 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34 32 7d  ..**.** {F13742}
23310 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
23320 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
23330 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  me16(S,N)] inter
23340 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
23350 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
23360 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76  the UTF-16 nativ
23370 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72  e byte order zer
23380 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
23390 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
233a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72  e.**          fr
233b0 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e 74 68  om which the Nth
233c0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f   result column o
233d0 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
233e0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a  statement] S is.
233f0 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 74 72  **          extr
23400 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69  acted, or NULL i
23410 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
23420 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72   of S is a gener
23430 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a  al expression.**
23440 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20            or if 
23450 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
23460 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f  te memory to sto
23470 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a  re the name..**.
23480 2a 2a 20 7b 46 31 33 37 34 33 7d 20 54 68 65 20  ** {F13743} The 
23490 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
234a0 74 61 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d  table_name(S,N)]
234b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
234c0 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
234d0 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20        the UTF-8 
234e0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
234f0 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c  name of the tabl
23500 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  e from which the
23510 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
23520 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f   result column o
23530 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
23540 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20  statement] S is 
23550 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20  extracted,.**   
23560 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69         or NULL i
23570 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
23580 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72   of S is a gener
23590 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a  al expression.**
235a0 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20            or if 
235b0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
235c0 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f  te memory to sto
235d0 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a  re the name..**.
235e0 2a 2a 20 7b 46 31 33 37 34 34 7d 20 54 68 65 20  ** {F13744} The 
235f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
23600 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e  table_name16(S,N
23610 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
23620 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
23630 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d          the UTF-
23640 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
23650 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  rder zero-termin
23660 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65  ated name of the
23670 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20   table.**       
23680 20 20 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68     from which th
23690 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e Nth result col
236a0 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70  umn of the [prep
236b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
236c0 53 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  S is.**         
236d0 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e   extracted, or N
236e0 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63  ULL if the Nth c
236f0 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20  olumn of S is a 
23700 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69  general expressi
23710 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  on.**          o
23720 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
23730 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
23740 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65  o store the name
23750 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34 35 7d  ..**.** {F13745}
23760 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
23770 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
23780 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
23790 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
237a0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
237b0 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
237c0 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68  nated name of th
237d0 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66  e table column f
237e0 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a  rom which the.**
237f0 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65            Nth re
23800 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  sult column of t
23810 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
23820 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74  tement] S is ext
23830 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20  racted,.**      
23840 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74      or NULL if t
23850 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
23860 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20   S is a general 
23870 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20  expression.**   
23880 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61         or if una
23890 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
238a0 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20  memory to store 
238b0 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  the name..**.** 
238c0 7b 46 31 33 37 34 36 7d 20 54 68 65 20 5b 73 71  {F13746} The [sq
238d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
238e0 67 69 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  gin_name16(S,N)]
238f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
23900 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
23910 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36        the UTF-16
23920 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
23930 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  er zero-terminat
23940 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74  ed name of the t
23950 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  able.**         
23960 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69   column from whi
23970 63 68 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ch the Nth resul
23980 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  t column of the.
23990 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
239a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
239b0 20 53 20 69 73 20 65 78 74 72 61 63 74 65 64 2c   S is extracted,
239c0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
239d0 4e 74 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20  Nth column.**   
239e0 20 20 20 20 20 20 20 6f 66 20 53 20 69 73 20 61         of S is a
239f0 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73   general express
23a00 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65  ion or if unable
23a10 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
23a20 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ory.**          
23a30 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d  to store the nam
23a40 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37 34 38  e..**.** {F13748
23a50 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  } The return val
23a60 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20  ues from.**     
23a70 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
23a80 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
23a90 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61  me | column meta
23aa0 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
23ab0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65  .**          are
23ac0 20 76 61 6c 69 64 20 66 6f 72 20 74 68 65 20 6c   valid for the l
23ad0 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 5b  ifetime of the [
23ae0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23af0 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nt].**          
23b00 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 65 6e 63  or until the enc
23b10 6f 64 69 6e 67 20 69 73 20 63 68 61 6e 67 65 64  oding is changed
23b20 20 62 79 20 61 6e 6f 74 68 65 72 20 6d 65 74 61   by another meta
23b30 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  data.**         
23b40 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20   interface call 
23b50 66 6f 72 20 74 68 65 20 73 61 6d 65 20 70 72 65  for the same pre
23b60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
23b70 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
23b80 2a 20 4c 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a  * LIMITATIONS:.*
23b90 2a 0a 2a 2a 20 7b 55 31 33 37 35 31 7d 20 49 66  *.** {U13751} If
23ba0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
23bb0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
23bc0 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20   more.**        
23bd0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
23be0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
23bf0 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
23c00 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
23c10 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 74 68            for th
23c20 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  e same [prepared
23c30 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
23c40 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
23c50 20 20 20 20 20 20 20 20 20 20 61 74 20 74 68 65            at the
23c60 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
23c70 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
23c80 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f  undefined..*/.co
23c90 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
23ca0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
23cb0 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
23cc0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
23cd0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
23ce0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
23cf0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
23d00 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
23d10 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
23d20 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
23d30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
23d40 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
23d50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
23d60 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
23d70 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
23d80 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
23d90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
23da0 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
23db0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
23dc0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
23dd0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
23de0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
23df0 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
23e00 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
23e10 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
23e20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 46 31  Query Result {F1
23e30 33 37 36 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  3760}.**.** The 
23e40 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
23e50 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
23e60 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
23e70 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
23e80 69 73 20 61 20 53 45 4c 45 43 54 20 73 74 61 74  is a SELECT stat
23e90 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
23ea0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
23eb0 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
23ec0 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 53  lt set of that S
23ed0 45 4c 45 43 54 20 69 73 20 61 20 74 61 62 6c 65  ELECT is a table
23ee0 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a   column (not an.
23ef0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
23f00 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20   subquery) then 
23f10 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
23f20 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
23f30 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75  * column is retu
23f40 72 6e 65 64 2e 20 20 49 66 20 74 68 65 20 4e 74  rned.  If the Nt
23f50 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
23f60 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
23f70 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
23f80 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
23f90 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
23fa0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
23fb0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
23fc0 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
23fd0 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20 7b 45 4e  F-8 encoded. {EN
23fe0 44 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  D}.**.** For exa
23ff0 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20  mple, given the 
24000 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
24010 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
24020 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
24030 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68  T);.**.** and th
24040 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
24050 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
24060 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45  iled:.**.** SELE
24070 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52  CT c1 + 1, c1 FR
24080 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69  OM t1;.**.** thi
24090 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20  s routine would 
240a0 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e  return the strin
240b0 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20  g "VARIANT" for 
240c0 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c  the second resul
240d0 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  t.** column (i==
240e0 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70  1), and a NULL p
240f0 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66  ointer for the f
24100 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75  irst result colu
24110 6d 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a  mn (i==0)..**.**
24120 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
24130 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
24140 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62  ping.  So just b
24150 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
24160 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
24170 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
24180 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
24190 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
241a0 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
241b0 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
241c0 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
241d0 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
241e0 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
241f0 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
24200 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
24210 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54  c not static.  T
24220 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69  ype.** is associ
24230 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69  ated with indivi
24240 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74  dual values, not
24250 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69   with the contai
24260 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ners.** used to 
24270 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65  hold those value
24280 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  s..**.** INVARIA
24290 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 37  NTS:.**.** {F137
242a0 36 31 7d 20 20 41 20 73 75 63 63 65 73 73 66 75  61}  A successfu
242b0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
242c0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
242d0 70 65 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 73  pe(S,N)] returns
242e0 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20   a.**           
242f0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
24300 55 54 46 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e  UTF-8 string con
24310 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63 6c  taining the decl
24320 61 72 65 64 20 64 61 74 61 74 79 70 65 0a 2a 2a  ared datatype.**
24330 20 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68             of th
24340 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
24350 68 61 74 20 61 70 70 65 61 72 73 20 61 73 20 74  hat appears as t
24360 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e  he Nth column (n
24370 75 6d 62 65 72 65 64 0a 2a 2a 20 20 20 20 20 20  umbered.**      
24380 20 20 20 20 20 66 72 6f 6d 20 30 29 20 6f 66 20       from 0) of 
24390 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 74  the result set t
243a0 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
243b0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a  statement] S..**
243c0 0a 2a 2a 20 7b 46 31 33 37 36 32 7d 20 20 41 20  .** {F13762}  A 
243d0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
243e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  to [sqlite3_colu
243f0 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c  mn_decltype16(S,
24400 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  N)].**          
24410 20 72 65 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d   returns a zero-
24420 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31  terminated UTF-1
24430 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
24440 64 65 72 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20  der string.**   
24450 20 20 20 20 20 20 20 20 63 6f 6e 74 61 69 6e 69          containi
24460 6e 67 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  ng the declared 
24470 64 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20  datatype of the 
24480 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
24490 74 20 61 70 70 65 61 72 73 0a 2a 2a 20 20 20 20  t appears.**    
244a0 20 20 20 20 20 20 20 61 73 20 74 68 65 20 4e 74         as the Nt
244b0 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72  h column (number
244c0 65 64 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68  ed from 0) of th
244d0 65 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20  e result set to 
244e0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
244f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24500 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b  ment] S..**.** {
24510 46 31 33 37 36 33 7d 20 20 49 66 20 4e 20 69 73  F13763}  If N is
24520 20 6c 65 73 73 20 74 68 61 6e 20 30 20 6f 72 20   less than 0 or 
24530 4e 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  N is greater tha
24540 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a  n or equal to.**
24550 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6e             the n
24560 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
24570 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
24580 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a  d statement] S,.
24590 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72 20  **           or 
245a0 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
245b0 6e 20 6f 66 20 53 20 69 73 20 61 6e 20 65 78 70  n of S is an exp
245c0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
245d0 65 72 79 20 72 61 74 68 65 72 0a 2a 2a 20 20 20  ery rather.**   
245e0 20 20 20 20 20 20 20 20 74 68 61 6e 20 61 20 74          than a t
245f0 61 62 6c 65 20 63 6f 6c 75 6d 6e 2c 20 6f 72 20  able column, or 
24600 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
24610 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 0a 2a  cation failure.*
24620 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75  *           occu
24630 72 73 20 64 75 72 69 6e 67 20 65 6e 63 6f 64 69  rs during encodi
24640 6e 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73 2c 20  ng conversions, 
24650 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
24660 20 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69    calls to [sqli
24670 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
24680 79 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20  ype(S,N)] or.** 
24690 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
246a0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
246b0 70 65 31 36 28 53 2c 4e 29 5d 20 72 65 74 75 72  pe16(S,N)] retur
246c0 6e 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74  n NULL..*/.const
246d0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
246e0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
246f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
24700 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
24710 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
24720 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
24730 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
24740 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
24750 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
24760 61 74 65 6d 65 6e 74 20 7b 46 31 33 32 30 30 7d  atement {F13200}
24770 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
24780 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24790 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
247a0 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
247b0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
247c0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
247d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
247e0 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
247f0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
24800 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
24810 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
24820 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
24830 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
24840 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
24850 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
24860 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
24870 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
24880 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
24890 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
248a0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
248b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
248c0 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
248d0 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
248e0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
248f0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
24900 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
24910 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
24920 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
24930 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
24940 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
24950 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
24960 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
24970 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
24980 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
24990 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
249a0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
249b0 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
249c0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
249d0 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
249e0 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
249f0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
24a00 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
24a10 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
24a20 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ed..**.** In the
24a30 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
24a40 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
24a50 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
24a60 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
24a70 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
24a80 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
24a90 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
24aa0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
24ab0 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68  USE]..** With th
24ac0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
24ad0 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
24ae0 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
24af0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
24b00 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
24b10 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
24b20 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
24b30 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d   [SQLITE_BUSY] m
24b40 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61  eans that the da
24b50 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61  tabase engine wa
24b60 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75  s unable to acqu
24b70 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ire the.** datab
24b80 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65  ase locks it nee
24b90 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62  ds to do its job
24ba0 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
24bb0 65 6e 74 20 69 73 20 61 20 43 4f 4d 4d 49 54 0a  ent is a COMMIT.
24bc0 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
24bd0 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
24be0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
24bf0 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
24c00 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
24c10 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
24c20 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
24c30 20 43 4f 4d 4d 49 54 20 61 6e 64 20 6f 63 63 75   COMMIT and occu
24c40 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65  rs within a.** e
24c50 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
24c60 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
24c70 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
24c80 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
24c90 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
24ca0 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  g..**.** [SQLITE
24cb0 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61  _DONE] means tha
24cc0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
24cd0 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
24ce0 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73  cuting.** succes
24cf0 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33  sfully.  sqlite3
24d00 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
24d10 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
24d20 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75  in on this virtu
24d30 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69  al.** machine wi
24d40 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c  thout first call
24d50 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
24d60 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  et()] to reset t
24d70 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  he virtual.** ma
24d80 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74  chine back to it
24d90 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e  s initial state.
24da0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
24db0 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
24dc0 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
24dd0 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
24de0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
24df0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
24e00 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
24e10 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
24e20 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
24e30 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
24e40 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
24e50 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
24e60 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
24e70 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
24e80 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
24e90 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
24ea0 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
24eb0 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
24ec0 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53  f data..**.** [S
24ed0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
24ee0 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
24ef0 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
24f00 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
24f10 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
24f20 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
24f30 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
24f40 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
24f50 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
24f60 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
24f70 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
24f80 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
24f90 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
24fa0 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 6c 65 67  .** With the leg
24fb0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61  acy interface, a
24fc0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
24fd0 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65  rror code (for e
24fe0 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49  xample,.** [SQLI
24ff0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
25000 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
25010 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
25020 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
25030 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
25040 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
25050 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
25060 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
25070 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
25080 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74   In the "v2" int
25090 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
250a0 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
250b0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
250c0 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
250d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
250e0 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
250f0 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
25100 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
25110 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
25120 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
25130 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
25140 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
25150 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25160 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
25170 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
25180 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
25190 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
251a0 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
251b0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
251c0 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
251d0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
251e0 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
251f0 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
25200 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
25210 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25220 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
25230 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
25240 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
25250 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
25260 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47  time..**.** <b>G
25270 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41  oofy Interface A
25280 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65  lert:</b> In the
25290 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
252a0 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  e, the sqlite3_s
252b0 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77  tep().** API alw
252c0 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65  ays returns a ge
252d0 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65  neric error code
252e0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
252f0 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a  , following any.
25300 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74  ** error other t
25310 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  han [SQLITE_BUSY
25320 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49  ] and [SQLITE_MI
25330 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74  SUSE].  You must
25340 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
25350 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
25360 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
25370 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
25380 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  ind one of the.*
25390 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  * specific [erro
253a0 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65  r codes] that be
253b0 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74  tter describes t
253c0 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20  he error..** We 
253d0 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20  admit that this 
253e0 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67  is a goofy desig
253f0 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20  n.  The problem 
25400 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a  has been fixed.*
25410 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20  * with the "v2" 
25420 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79  interface.  If y
25430 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f  ou prepare all o
25440 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65  f your SQL state
25450 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65  ments.** using e
25460 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
25470 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
25480 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
25490 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64  16_v2()] instead
254a0 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
254b0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
254c0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
254d0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
254e0 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
254f0 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
25500 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
25510 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
25520 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
25530 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
25540 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
25550 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
25560 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
25570 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
25580 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 32 30 32 7d 20  .**.** {F13202} 
25590 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   If the [prepare
255a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
255b0 73 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 75  s ready to be ru
255c0 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  n, then.**      
255d0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 74       [sqlite3_st
255e0 65 70 28 53 29 5d 20 61 64 76 61 6e 63 65 73 20  ep(S)] advances 
255f0 74 68 61 74 20 70 72 65 70 61 72 65 64 20 73 74  that prepared st
25600 61 74 65 6d 65 6e 74 20 75 6e 74 69 6c 0a 2a 2a  atement until.**
25610 20 20 20 20 20 20 20 20 20 20 20 63 6f 6d 70 6c             compl
25620 65 74 69 6f 6e 20 6f 72 20 75 6e 74 69 6c 20 69  etion or until i
25630 74 20 69 73 20 72 65 61 64 79 20 74 6f 20 72 65  t is ready to re
25640 74 75 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77  turn another row
25650 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
25660 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 2c       result set,
25670 20 6f 72 20 75 6e 74 69 6c 20 61 6e 20 5b 73 71   or until an [sq
25680 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20  lite3_interrupt 
25690 7c 20 69 6e 74 65 72 72 75 70 74 5d 0a 2a 2a 20  | interrupt].** 
256a0 20 20 20 20 20 20 20 20 20 20 6f 72 20 61 20 72            or a r
256b0 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 6f 63  un-time error oc
256c0 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  curs..**.** {F15
256d0 33 30 34 7d 20 20 57 68 65 6e 20 61 20 63 61 6c  304}  When a cal
256e0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
256f0 65 70 28 53 29 5d 20 63 61 75 73 65 73 20 74 68  ep(S)] causes th
25700 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
25710 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20  ement].**       
25720 20 20 20 20 53 20 74 6f 20 72 75 6e 20 74 6f 20      S to run to 
25730 63 6f 6d 70 6c 65 74 69 6f 6e 2c 20 74 68 65 20  completion, the 
25740 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
25750 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a   [SQLITE_DONE]..
25760 2a 2a 0a 2a 2a 20 7b 46 31 35 33 30 36 7d 20 20  **.** {F15306}  
25770 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b  When a call to [
25780 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
25790 20 73 74 6f 70 73 20 62 65 63 61 75 73 65 20 69   stops because i
257a0 74 20 69 73 20 72 65 61 64 79 20 74 6f 0a 2a 2a  t is ready to.**
257b0 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72             retur
257c0 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66  n another row of
257d0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2c   the result set,
257e0 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c   it returns [SQL
257f0 49 54 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20  ITE_ROW]..**.** 
25800 7b 46 31 35 33 30 38 7d 20 20 49 66 20 61 20 63  {F15308}  If a c
25810 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
25820 73 74 65 70 28 53 29 5d 20 65 6e 63 6f 75 6e 74  step(S)] encount
25830 65 72 73 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20  ers an.**       
25840 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74      [sqlite3_int
25850 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75  errupt | interru
25860 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d  pt] or a run-tim
25870 65 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20  e error,.**     
25880 20 20 20 20 20 20 69 74 20 72 65 74 75 72 6e 73        it returns
25890 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
258a0 65 72 72 6f 72 20 63 6f 64 65 20 74 68 61 74 20  error code that 
258b0 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a  is not one of.**
258c0 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49             [SQLI
258d0 54 45 5f 4f 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f  TE_OK], [SQLITE_
258e0 52 4f 57 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROW], or [SQLITE
258f0 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46  _DONE]..**.** {F
25900 31 35 33 31 30 7d 20 20 49 66 20 61 6e 20 5b 73  15310}  If an [s
25910 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
25920 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 20 6f 72   | interrupt] or
25930 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
25940 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f  r.**           o
25950 63 63 75 72 73 20 64 75 72 69 6e 67 20 61 20 63  ccurs during a c
25960 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
25970 73 74 65 70 28 53 29 5d 0a 2a 2a 20 20 20 20 20  step(S)].**     
25980 20 20 20 20 20 20 66 6f 72 20 61 20 5b 70 72 65        for a [pre
25990 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
259a0 20 53 20 63 72 65 61 74 65 64 20 75 73 69 6e 67   S created using
259b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6c 65  .**           le
259c0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 73 20  gacy interfaces 
259d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
259e0 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ()] or.**       
259f0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65      [sqlite3_pre
25a00 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20  pare16()], then 
25a10 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  the function ret
25a20 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
25a30 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
25a40 5f 45 52 52 4f 52 5d 2c 20 5b 53 51 4c 49 54 45  _ERROR], [SQLITE
25a50 5f 42 55 53 59 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BUSY], or [SQLI
25a60 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2f 0a 69  TE_MISUSE]..*/.i
25a70 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  nt sqlite3_step(
25a80 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
25a90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25aa0 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   Number of colum
25ab0 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73  ns in a result s
25ac0 65 74 20 7b 46 31 33 37 37 30 7d 0a 2a 2a 0a 2a  et {F13770}.**.*
25ad0 2a 20 52 65 74 75 72 6e 73 20 74 68 65 20 6e 75  * Returns the nu
25ae0 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69  mber of values i
25af0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
25b00 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
25b10 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  set..**.** INVAR
25b20 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31  IANTS:.**.** {F1
25b30 33 37 37 31 7d 20 20 41 66 74 65 72 20 61 20 63  3771}  After a c
25b40 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
25b50 73 74 65 70 28 53 29 5d 20 74 68 61 74 20 72 65  step(S)] that re
25b60 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f  turns [SQLITE_RO
25b70 57 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  W],.**          
25b80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 61   the [sqlite3_da
25b90 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75  ta_count(S)] rou
25ba0 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  tine will return
25bb0 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 0a   the same value.
25bc0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 73 20  **           as 
25bd0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
25be0 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 66 75  umn_count(S)] fu
25bf0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46  nction..**.** {F
25c00 31 33 37 37 32 7d 20 20 41 66 74 65 72 20 5b 73  13772}  After [s
25c10 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
25c20 68 61 73 20 72 65 74 75 72 6e 65 64 20 61 6e 79  has returned any
25c30 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
25c40 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  n.**           [
25c50 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 62  SQLITE_ROW] or b
25c60 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73  efore [sqlite3_s
25c70 74 65 70 28 53 29 5d 20 68 61 73 20 62 65 65 6e  tep(S)] has been
25c80 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 0a 2a   called on the.*
25c90 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  *           [pre
25ca0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25cb0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 74   for the first t
25cc0 69 6d 65 20 73 69 6e 63 65 20 69 74 20 77 61 73  ime since it was
25cd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
25ce0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
25cf0 20 70 72 65 70 61 72 65 64 5d 20 6f 72 20 5b 73   prepared] or [s
25d00 71 6c 69 74 65 33 5f 72 65 73 65 74 20 7c 20 72  qlite3_reset | r
25d10 65 73 65 74 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  eset],.**       
25d20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33      the [sqlite3
25d30 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20  _data_count(S)] 
25d40 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
25d50 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  zero..*/.int sql
25d60 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
25d70 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
25d80 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
25d90 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
25da0 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b 46 31  al Datatypes {F1
25db0 30 32 36 35 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  0265}.** KEYWORD
25dc0 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
25dd0 2a 0a 2a 2a 20 7b 46 31 30 32 36 36 7d 20 45 76  *.** {F10266} Ev
25de0 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
25df0 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
25e00 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
25e10 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
25e20 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
25e30 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
25e40 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
25e50 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
25e60 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
25e70 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
25e80 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
25e90 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20  > NULL.** </ul> 
25ea0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  {END}.**.** Thes
25eb0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
25ec0 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
25ed0 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
25ee0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
25ef0 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
25f00 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
25f10 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
25f20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
25f30 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
25f40 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
25f50 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
25f60 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
25f70 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
25f80 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
25f90 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
25fa0 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
25fb0 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
25fc0 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
25fd0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
25fe0 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
25ff0 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
26000 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
26010 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
26020 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
26030 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
26040 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
26050 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
26060 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
26070 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
26080 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
26090 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
260a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
260b0 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
260c0 6d 20 41 20 51 75 65 72 79 20 7b 46 31 33 38 30  m A Query {F1380
260d0 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0}.** KEYWORDS: 
260e0 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  {column access f
260f0 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
26100 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66  These routines f
26110 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20  orm the "result 
26120 73 65 74 20 71 75 65 72 79 22 20 69 6e 74 65 72  set query" inter
26130 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  face..**.** Thes
26140 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
26150 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
26160 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  out a single col
26170 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
26180 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77  nt.** result row
26190 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 49 6e   of a query.  In
261a0 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20   every case the 
261b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
261c0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
261d0 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
261e0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
261f0 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74  is being evaluat
26200 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
26210 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20  _stmt*].** that 
26220 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
26230 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
26240 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
26250 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
26260 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f  .** and the seco
26270 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
26280 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
26290 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
262a0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
262b0 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
262c0 65 64 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73  ed.  The leftmos
262d0 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
262e0 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74  result set has t
262f0 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a  he index 0..**.*
26300 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
26310 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
26320 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
26330 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
26340 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
26350 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
26360 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
26370 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
26380 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
26390 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
263a0 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
263b0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
263c0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
263d0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
263e0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
263f0 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
26400 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
26410 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
26420 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
26430 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
26440 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
26450 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
26460 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
26470 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
26480 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
26490 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
264a0 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
264b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
264c0 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
264d0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
264e0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
264f0 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
26500 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
26510 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
26520 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
26530 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
26540 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
26550 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
26560 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
26570 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
26580 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
26590 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
265a0 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
265b0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
265c0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
265d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
265e0 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
265f0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
26600 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
26610 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
26620 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
26630 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
26640 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
26650 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61   The returned va
26660 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  lue is one of [S
26670 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a  QLITE_INTEGER],.
26680 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ** [SQLITE_FLOAT
26690 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d  ], [SQLITE_TEXT]
266a0 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c  , [SQLITE_BLOB],
266b0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   or [SQLITE_NULL
266c0 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a  ].  The value.**
266d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
266e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
266f0 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
26700 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65  ngful if no type
26710 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  .** conversions 
26720 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73  have occurred as
26730 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77   described below
26740 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20  .  After a type 
26750 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74  conversion,.** t
26760 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
26770 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
26780 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e  umn_type() is un
26790 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65  defined.  Future
267a0 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
267b0 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67  SQLite may chang
267c0 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
267d0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  f sqlite3_column
267e0 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f  _type().** follo
267f0 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76  wing a type conv
26800 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66  ersion..**.** If
26810 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
26820 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73   BLOB or UTF-8 s
26830 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
26840 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
26850 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  tes().** routine
26860 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
26870 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
26880 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
26890 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72  ing..** If the r
268a0 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
268b0 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
268c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
268d0 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
268e0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
268f0 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
26900 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
26910 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49  r of bytes..** I
26920 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
26930 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
26940 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
26950 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
26960 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
26970 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
26980 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
26990 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
269a0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
269b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
269c0 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
269d0 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  ng..** The value
269e0 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e   returned does n
269f0 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
26a00 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61  ero terminator a
26a10 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20  t the end.** of 
26a20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72  the string.  For
26a30 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
26a40 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
26a50 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
26a60 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
26a70 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
26a80 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
26a90 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67  rs..**.** String
26aa0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
26ab0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
26ac0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
26ad0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
26ae0 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
26af0 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
26b00 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  ys zero terminat
26b10 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 0a  ed.  The return.
26b20 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
26b30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
26b40 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
26b50 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e  ength BLOB is an
26b60 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f   arbitrary.** po
26b70 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20  inter, possibly 
26b80 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  even a NULL poin
26b90 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ter..**.** The s
26ba0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
26bb0 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20  tes16() routine 
26bc0 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71  is similar to sq
26bd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
26be0 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76  es().** but leav
26bf0 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  es the result in
26c00 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
26c10 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73  e byte order ins
26c20 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a  tead of UTF-8..*
26c30 2a 20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  * The zero termi
26c40 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63  nator is not inc
26c50 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f  luded in this co
26c60 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  unt..**.** The o
26c70 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
26c80 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
26c90 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e  n_value()] is an
26ca0 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
26cb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
26cc0 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72  object.  An unpr
26cd0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
26ce0 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20  value object.** 
26cf0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
26d00 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62   with [sqlite3_b
26d10 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
26d20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
26d30 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
26d40 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
26d50 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
26d60 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
26d70 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
26d80 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
26d90 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
26da0 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
26db0 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
26dc0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
26dd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
26de0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
26df0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
26e00 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
26e10 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e  e_bytes()], then
26e20 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
26e30 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
26e40 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
26e50 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
26e60 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68  ert the value wh
26e70 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e  ere appropriate.
26e80 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
26e90 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
26ea0 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
26eb0 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
26ec0 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
26ed0 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
26ee0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
26ef0 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
26f00 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20  ally to perform 
26f10 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  the.** conversio
26f20 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  n automatically.
26f30 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20    The following 
26f40 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68  table details th
26f50 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a  e conversions.**
26f60 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65   that are applie
26f70 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d:.**.** <blockq
26f80 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
26f90 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
26fa0 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c  tr><th> Internal
26fb0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65  <br>Type <th> Re
26fc0 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20  quested<br>Type 
26fd0 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e  <th>  Conversion
26fe0 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
26ff0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e   NULL    <td> IN
27000 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73  TEGER   <td> Res
27010 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e  ult is 0.** <tr>
27020 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
27030 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
27040 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a  > Result is 0.0.
27050 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
27060 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  L    <td>   TEXT
27070 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
27080 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a  is NULL pointer.
27090 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
270a0 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  L    <td>   BLOB
270b0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
270c0 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a  is NULL pointer.
270d0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
270e0 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  GER  <td>  FLOAT
270f0 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
27100 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f   from integer to
27110 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <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 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
27140 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
27150 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a  of the integer.*
27160 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
27170 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  ER  <td>   BLOB 
27180 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
27190 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a  INTEGER->TEXT.**
271a0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
271b0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
271c0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
271d0 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74  rom float to int
271e0 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
271f0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
27200 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
27210 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
27220 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74   the float.** <t
27230 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
27240 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
27250 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41  td> Same as FLOA
27260 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  T->TEXT.** <tr><
27270 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
27280 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
27290 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c   Use atoi().** <
272a0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
272b0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
272c0 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a  <td> Use atof().
272d0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
272e0 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  T    <td>   BLOB
272f0 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e      <td> No chan
27300 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ge.** <tr><td>  
27310 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54  BLOB    <td> INT
27320 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
27330 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
27340 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c   use atoi().** <
27350 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
27360 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
27370 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20  <td> Convert to 
27380 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74  TEXT then use at
27390 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
273a0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
273b0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64   TEXT    <td> Ad
273c0 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  d a zero termina
273d0 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a  tor if needed.**
273e0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
273f0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
27400 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65   The table above
27410 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65   makes reference
27420 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c   to standard C l
27430 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73  ibrary functions
27440 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61   atoi().** and a
27450 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64  tof().  SQLite d
27460 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75  oes not really u
27470 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  se these functio
27480 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a  ns.  It has its.
27490 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e  ** own equivalen
274a0 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69  t internal routi
274b0 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29  nes.  The atoi()
274c0 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65   and atof() name
274d0 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e  s are.** used in
274e0 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62   the table for b
274f0 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75  revity and becau
27500 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69  se they are fami
27510 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20  liar to most.** 
27520 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a  C programmers..*
27530 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
27540 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
27550 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
27560 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
27570 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
27580 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
27590 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
275a0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
275b0 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
275c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
275d0 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
275e0 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
275f0 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
27600 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
27610 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
27620 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
27630 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
27640 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
27650 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
27660 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
27670 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27680 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
27690 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
276a0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
276b0 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
276c0 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
276d0 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
276e0 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
276f0 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
27700 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
27710 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
27720 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
27730 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
27740 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
27750 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
27760 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
27770 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
27780 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
27790 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
277a0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
277b0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
277c0 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
277d0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
277e0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
277f0 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
27800 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
27810 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
27820 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
27830 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
27840 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
27850 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f  * </ul>.**.** Co
27860 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
27870 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
27880 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
27890 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
278a0 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
278b0 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
278c0 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
278d0 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
278e0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
278f0 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
27900 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
27910 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68  points to will h
27920 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
27930 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
27940 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
27950 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
27960 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
27970 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
27980 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
27990 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
279a0 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
279b0 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
279c0 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
279d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65  ..**.** The safe
279e0 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74  st and easiest t
279f0 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63  o remember polic
27a00 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
27a10 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
27a20 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
27a30 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
27a40 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  *.** <ul>.**  <l
27a50 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
27a60 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
27a70 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
27a80 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
27a90 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
27aa0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
27ab0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
27ac0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
27ad0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
27ae0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
27af0 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
27b00 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
27b10 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
27b20 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
27b30 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
27b40 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
27b50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
27b60 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  xt(),.** sqlite3
27b70 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
27b80 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
27b90 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
27ba0 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
27bb0 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  sult.** into the
27bc0 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c   desired format,
27bd0 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
27be0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
27bf0 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  s() or.** sqlite
27c00 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
27c10 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  () to find the s
27c20 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
27c30 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
27c40 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  alls.** to sqlit
27c50 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
27c60 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
27c70 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
27c80 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
27c90 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
27ca0 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20  6(), and do not 
27cb0 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
27cc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
27cd0 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c  16().** with cal
27ce0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
27cf0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
27d00 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73  .** The pointers
27d10 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61   returned are va
27d20 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65  lid until a type
27d30 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
27d40 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62  rs as.** describ
27d50 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74  ed above, or unt
27d60 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  il [sqlite3_step
27d70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
27d80 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
27d90 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
27da0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  ()] is called.  
27db0 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
27dc0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
27dd0 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
27de0 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
27df0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
27e00 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74  b>not</b> pass t
27e10 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
27e20 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rned.** [sqlite3
27e30 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
27e40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
27e50 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
27e60 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
27e70 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  free()]..**.** I
27e80 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
27e90 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
27ea0 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76  rs during the ev
27eb0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a  aluation of any.
27ec0 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ** of these rout
27ed0 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20  ines, a default 
27ee0 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
27ef0 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
27f00 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68  value.** is eith
27f10 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30  er the integer 0
27f20 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  , the floating p
27f30 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c  oint number 0.0,
27f40 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   or a NULL.** po
27f50 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65  inter.  Subseque
27f60 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
27f70 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
27f80 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  will return.** [
27f90 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
27fa0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
27fb0 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38 30 33 7d 20  .**.** {F13803} 
27fc0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
27fd0 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 69  umn_blob(S,N)] i
27fe0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
27ff0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
28000 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
28010 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
28020 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
28030 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
28040 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20    the [prepared 
28050 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74  statement] S int
28060 6f 20 61 20 42 4c 4f 42 20 61 6e 64 20 74 68 65  o a BLOB and the
28070 6e 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20  n returns a.**  
28080 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20          pointer 
28090 74 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64  to the converted
280a0 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46   value..**.** {F
280b0 31 33 38 30 36 7d 20 54 68 65 20 5b 73 71 6c 69  13806} The [sqli
280c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
280d0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
280e0 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
280f0 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
28100 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
28110 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 28  BLOB or string (
28120 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
28130 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
28140 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20  o terminator on 
28150 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74  the string) that
28160 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79   was returned by
28170 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
28180 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
28190 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
281a0 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20  lumn_blob(S,N)] 
281b0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
281c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
281d0 65 78 74 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a  ext(S,N)]..**.**
281e0 20 7b 46 31 33 38 30 39 7d 20 54 68 65 20 5b 73   {F13809} The [s
281f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
28200 74 65 73 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65  tes16(S,N)] inte
28210 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
28220 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
28230 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
28240 20 74 68 65 20 73 74 72 69 6e 67 20 28 65 78 63   the string (exc
28250 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a  lusive of the.**
28260 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
28270 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65  erminator on the
28280 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61   string) that wa
28290 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
282a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f  e.**          mo
282b0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
282c0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
282d0 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a  n_text16(S,N)]..
282e0 2a 2a 0a 2a 2a 20 7b 46 31 33 38 31 32 7d 20 54  **.** {F13812} T
282f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
28300 6d 6e 5f 64 6f 75 62 6c 65 28 53 2c 4e 29 5d 20  mn_double(S,N)] 
28310 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
28320 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
28330 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
28340 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
28350 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
28360 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  et for the.**   
28370 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
28380 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
28390 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  to a floating po
283a0 69 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a  int value and.**
283b0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
283c0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74  s a copy of that
283d0 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46   value..**.** {F
283e0 31 33 38 31 35 7d 20 54 68 65 20 5b 73 71 6c 69  13815} The [sqli
283f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53  te3_column_int(S
28400 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
28410 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
28420 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
28430 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
28440 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
28450 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a  ult set for the.
28460 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
28470 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28480 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74   S into a 64-bit
28490 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
284a0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
284b0 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65  returns the lowe
284c0 72 20 33 32 20 62 69 74 73 20 6f 66 20 74 68 61  r 32 bits of tha
284d0 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
284e0 20 7b 46 31 33 38 31 38 7d 20 54 68 65 20 5b 73   {F13818} The [s
284f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
28500 74 36 34 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  t64(S,N)] interf
28510 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
28520 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
28530 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
28540 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
28550 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
28560 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
28570 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28580 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36  ment] S into a 6
28590 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
285a0 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20  eger and.**     
285b0 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63       returns a c
285c0 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65  opy of that inte
285d0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 38  ger..**.** {F138
285e0 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  21} The [sqlite3
285f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e  _column_text(S,N
28600 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
28610 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
28620 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
28630 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
28640 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
28650 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
28660 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61        the [prepa
28670 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
28680 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72   into a zero-ter
28690 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
286a0 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
286b0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
286c0 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
286d0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tring..**.** {F1
286e0 33 38 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  3824} The [sqlit
286f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
28700 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
28710 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
28720 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f            Nth co
28730 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
28740 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
28750 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68  esult set for th
28760 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
28770 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28780 74 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f  t] S into a zero
28790 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79  -terminated 2-by
287a0 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  te.**          a
287b0 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61  ligned UTF-16 na
287c0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
287d0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
287e0 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ns.**          a
287f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
28800 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
28810 46 31 33 38 32 37 7d 20 54 68 65 20 5b 73 71 6c  F13827} The [sql
28820 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
28830 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
28840 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
28850 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c       one of [SQL
28860 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49  ITE_NULL], [SQLI
28870 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51  TE_INTEGER], [SQ
28880 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20  LITE_FLOAT],.** 
28890 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
288a0 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49  _TEXT], or [SQLI
288b0 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72  TE_BLOB] as appr
288c0 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20  opriate for.**  
288d0 20 20 20 20 20 20 20 20 74 68 65 20 4e 74 68 20          the Nth 
288e0 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
288f0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
28900 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
28910 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
28920 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28930 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46  ent] S..**.** {F
28940 31 33 38 33 30 7d 20 54 68 65 20 5b 73 71 6c 69  13830} The [sqli
28950 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
28960 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
28970 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20   returns a.**   
28980 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74         pointer t
28990 6f 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65  o an [unprotecte
289a0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
289b0 20 6f 62 6a 65 63 74 20 66 6f 72 20 74 68 65 0a   object for the.
289c0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
289d0 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
289e0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
289f0 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
28a00 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
28a10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28a20 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74  ent] S..*/.const
28a30 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
28a40 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
28a50 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
28a60 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
28a70 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
28a80 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
28a90 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
28aa0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
28ab0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
28ac0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
28ad0 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
28ae0 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
28af0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
28b00 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
28b10 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
28b20 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
28b30 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ol);.sqlite3_int
28b40 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
28b50 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
28b60 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
28b70 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
28b80 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
28b90 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
28ba0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
28bb0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
28bc0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
28bd0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
28be0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
28bf0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
28c00 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
28c10 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
28c20 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
28c30 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
28c40 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
28c50 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
28c60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28c70 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
28c80 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
28c90 62 6a 65 63 74 20 7b 46 31 33 33 30 30 7d 0a 2a  bject {F13300}.*
28ca0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
28cb0 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
28cc0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
28cd0 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
28ce0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
28cf0 0a 2a 2a 20 49 66 20 74 68 65 20 73 74 61 74 65  .** If the state
28d00 6d 65 6e 74 20 77 61 73 20 65 78 65 63 75 74 65  ment was execute
28d10 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f  d successfully o
28d20 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61  r not executed a
28d30 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53  t all, then.** S
28d40 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75  QLITE_OK is retu
28d50 72 6e 65 64 2e 20 49 66 20 65 78 65 63 75 74 69  rned. If executi
28d60 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d  on of the statem
28d70 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20  ent failed then 
28d80 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  an.** [error cod
28d90 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  e] or [extended 
28da0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
28db0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
28dc0 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
28dd0 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
28de0 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68   point during th
28df0 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  e execution of t
28e00 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
28e10 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20  statement].  If 
28e20 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68  the virtual mach
28e30 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63  ine has not.** c
28e40 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
28e50 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75  on when this rou
28e60 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20  tine is called, 
28e70 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20  that is like.** 
28e80 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20  encountering an 
28e90 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c  error or an [sql
28ea0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c  ite3_interrupt |
28eb0 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20   interrupt]..** 
28ec0 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74  Incomplete updat
28ed0 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64  es may be rolled
28ee0 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61   back and transa
28ef0 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c  ctions canceled,
28f00 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  .** depending on
28f10 20 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63   the circumstanc
28f20 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b  es, and the.** [
28f30 65 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75  error code] retu
28f40 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51  rned will be [SQ
28f50 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a  LITE_ABORT]..**.
28f60 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
28f70 2a 0a 2a 2a 20 7b 46 31 31 33 30 32 7d 20 54 68  *.** {F11302} Th
28f80 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  e [sqlite3_final
28f90 69 7a 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63  ize(S)] interfac
28fa0 65 20 64 65 73 74 72 6f 79 73 20 74 68 65 0a 2a  e destroys the.*
28fb0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
28fc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
28fd0 53 20 61 6e 64 20 72 65 6c 65 61 73 65 73 20 61  S and releases a
28fe0 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  ll.**          m
28ff0 65 6d 6f 72 79 20 61 6e 64 20 66 69 6c 65 20 72  emory and file r
29000 65 73 6f 75 72 63 65 73 20 68 65 6c 64 20 62 79  esources held by
29010 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a   that object..**
29020 0a 2a 2a 20 7b 46 31 31 33 30 34 7d 20 49 66 20  .** {F11304} If 
29030 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
29040 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
29050 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
29060 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
29070 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29080 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 61 6e  t] S returned an
29090 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20   error,.**      
290a0 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65      then [sqlite
290b0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 72  3_finalize(S)] r
290c0 65 74 75 72 6e 73 20 74 68 61 74 20 73 61 6d 65  eturns that same
290d0 20 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73   error..*/.int s
290e0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
290f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
29100 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
29110 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
29120 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
29130 74 20 4f 62 6a 65 63 74 20 7b 46 31 33 33 33 30  t Object {F13330
29140 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
29150 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63  te3_reset() func
29160 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
29170 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61  o reset a [prepa
29180 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
29190 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f  * object back to
291a0 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
291b0 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20  te, ready to be 
291c0 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20  re-executed..** 
291d0 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
291e0 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
291f0 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
29200 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
29210 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
29220 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
29230 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
29240 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
29250 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
29260 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
29270 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
29280 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
29290 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 32 7d 20 54  **.** {F11332} T
292a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
292b0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
292c0 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
292d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
292e0 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 61  S.**          ba
292f0 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e  ck to the beginn
29300 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72  ing of its progr
29310 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33  am..**.** {F1133
29320 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  4} If the most r
29330 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
29340 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
29350 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
29360 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
29370 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
29380 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
29390 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
293a0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ],.**          o
293b0 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
293c0 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
293d0 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
293e0 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20  led on S,.**    
293f0 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69        then [sqli
29400 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
29410 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
29420 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 31 33 33 36  ]..**.** {F11336
29430 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  } If the most re
29440 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
29450 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
29460 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
29470 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
29480 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
29490 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
294a0 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  en.**          [
294b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
294c0 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
294d0 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
294e0 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  code]..**.** {F1
294f0 31 33 33 38 7d 20 54 68 65 20 5b 73 71 6c 69 74  1338} The [sqlit
29500 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
29510 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
29520 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
29530 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  s.**          of
29540 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69   any [sqlite3_bi
29550 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73  nd_blob|bindings
29560 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] on the [prepar
29570 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
29580 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
29590 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
295a0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
295b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
295c0 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
295d0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b 46  SQL Functions {F
295e0 31 36 31 30 30 7d 0a 2a 2a 20 4b 45 59 57 4f 52  16100}.** KEYWOR
295f0 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
29600 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
29610 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
29620 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
29630 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
29640 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
29650 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
29660 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
29670 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77  }.**.** These tw
29680 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  o functions (col
29690 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
296a0 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
296b0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
296c0 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
296d0 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
296e0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
296f0 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
29700 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
29710 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing 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 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
29740 79 20 64 69 66 66 65 72 65 6e 63 65 20 62 65 74  y difference bet
29750 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20  ween the.** two 
29760 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  is that the seco
29770 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  nd parameter, th
29780 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73  e name of the (s
29790 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20  calar) function 
297a0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2c  or.** aggregate,
297b0 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55   is encoded in U
297c0 54 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 33  TF-8 for sqlite3
297d0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
297e0 28 29 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a  () and UTF-16.**
297f0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
29800 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
29810 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
29820 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
29830 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
29840 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
29850 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
29860 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
29870 64 64 65 64 2e 20 20 49 66 20 61 20 73 69 6e 67  dded.  If a sing
29880 6c 65 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20  le program uses 
29890 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61  more than one da
298a0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
298b0 74 69 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c 79 2c  tion internally,
298c0 20 74 68 65 6e 20 53 51 4c 20 66 75 6e 63 74 69   then SQL functi
298d0 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  ons must be adde
298e0 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74  d individually t
298f0 6f 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 62 61  o.** each databa
29900 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a  se connection..*
29910 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
29920 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
29930 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
29940 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
29950 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
29960 64 65 66 69 6e 65 64 2e 20 20 54 68 65 20 6c 65  defined.  The le
29970 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65  ngth of the name
29980 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32   is limited to 2
29990 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73  55 bytes, exclus
299a0 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65  ive of.** the ze
299b0 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro-terminator.  
299c0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61  Note that the na
299d0 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  me length limit 
299e0 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74  is in bytes, not
299f0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20  .** characters. 
29a00 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
29a10 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
29a20 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
29a30 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
29a40 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45  ult in [SQLITE_E
29a50 52 52 4f 52 5d 20 62 65 69 6e 67 20 72 65 74 75  RROR] being retu
29a60 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
29a70 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
29a80 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
29a90 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
29aa0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
29ab0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
29ac0 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20   takes. If this 
29ad0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67  parameter is neg
29ae0 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
29af0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
29b00 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
29b10 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
29b20 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a   of arguments..*
29b30 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20  *.** The fourth 
29b40 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
29b50 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
29b60 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  hat.** [SQLITE_U
29b70 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
29b80 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
29b90 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
29ba0 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
29bb0 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66  ters.  Any SQL f
29bc0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
29bd0 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  tation should be
29be0 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
29bf0 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38   work with UTF-8
29c00 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55  , UTF-16le, or U
29c10 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f  TF-16be.  But so
29c20 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  me implementatio
29c30 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72  ns may be.** mor
29c40 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68  e efficient with
29c50 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68   one encoding th
29c60 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20  an another.  It 
29c70 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a  is allowed to.**
29c80 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
29c90 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
29ca0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65  ) or sqlite3_cre
29cb0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
29cc0 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d   multiple.** tim
29cd0 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  es with the same
29ce0 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69   function but wi
29cf0 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c  th different val
29d00 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e  ues of eTextRep.
29d10 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c  .** When multipl
29d20 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
29d30 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
29d40 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
29d50 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
29d60 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
29d70 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
29d80 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
29d90 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
29da0 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65  ion..** If there
29db0 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c   is only a singl
29dc0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
29dd0 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20   which does not 
29de0 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a  care what text.*
29df0 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  * encoding is us
29e00 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ed, then the fou
29e10 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rth argument sho
29e20 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  uld be [SQLITE_A
29e30 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  NY]..**.** The f
29e40 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
29e50 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
29e60 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
29e70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
29e80 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
29e90 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
29ea0 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
29eb0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
29ec0 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a  er_data()]..**.*
29ed0 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65  * The seventh, e
29ee0 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20  ighth and ninth 
29ef0 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e  parameters, xFun
29f00 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  c, xStep and xFi
29f10 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e  nal, are.** poin
29f20 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61  ters to C-langua
29f30 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ge functions tha
29f40 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
29f50 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
29f60 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 41 20  ** aggregate. A 
29f70 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
29f80 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
29f90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
29fa0 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63  f the xFunc.** c
29fb0 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55  allback only, NU
29fc0 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75  LL pointers shou
29fd0 6c 64 20 62 65 20 70 61 73 73 65 64 20 61 73 20  ld be passed as 
29fe0 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46  the xStep and xF
29ff0 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65  inal.** paramete
2a000 72 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65  rs. An aggregate
2a010 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
2a020 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
2a030 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65  entation of xSte
2a040 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20  p.** and xFinal 
2a050 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20  and NULL should 
2a060 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46  be passed for xF
2a070 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61  unc. To delete a
2a080 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51  n existing.** SQ
2a090 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
2a0a0 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
2a0b0 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65  LL for all three
2a0c0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
2a0d0 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  cks..**.** It is
2a0e0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65   permitted to re
2a0f0 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20  gister multiple 
2a100 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2a110 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66  of the same.** f
2a120 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68  unctions with th
2a130 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20  e same name but 
2a140 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66  with either diff
2a150 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66  ering numbers of
2a160 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  .** arguments or
2a170 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65   differing prefe
2a180 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
2a190 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ngs.  SQLite wil
2a1a0 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
2a1b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74  lementation most
2a1c0 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
2a1d0 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
2a1e0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
2a1f0 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ction is used..*
2a200 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
2a210 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30 33 7d 20  .**.** {F16103} 
2a220 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
2a230 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2a240 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 68 61  ] interface beha
2a250 76 65 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20  ves exactly.**  
2a260 20 20 20 20 20 20 20 20 6c 69 6b 65 20 5b 73 71          like [sq
2a270 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2a280 63 74 69 6f 6e 28 29 5d 20 69 6e 20 65 76 65 72  ction()] in ever
2a290 79 20 77 61 79 20 65 78 63 65 70 74 20 74 68 61  y way except tha
2a2a0 74 20 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  t it.**         
2a2b0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
2a2c0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 20 61 72  zFunctionName ar
2a2d0 67 75 6d 65 6e 74 20 61 73 20 7a 65 72 6f 2d 74  gument as zero-t
2a2e0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36  erminated UTF-16
2a2f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 74  .**          nat
2a300 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
2a310 6e 73 74 65 61 64 20 6f 66 20 61 73 20 7a 65 72  nstead of as zer
2a320 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
2a330 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30  -8..**.** {F1610
2a340 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  6} A successful 
2a350 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a  invocation of.**
2a360 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73            the [s
2a370 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2a380 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e  nction(D,X,N,E,.
2a390 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ..)] interface r
2a3a0 65 67 69 73 74 65 72 73 0a 2a 2a 20 20 20 20 20  egisters.**     
2a3b0 20 20 20 20 20 6f 72 20 72 65 70 6c 61 63 65 73       or replaces
2a3c0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2a3d0 6f 6e 73 20 69 6e 20 74 68 65 20 5b 64 61 74 61  ons in the [data
2a3e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2a3f0 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75   D.**          u
2a400 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
2a410 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2a420 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20 4e  n named X with N
2a430 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20   parameters.**  
2a440 20 20 20 20 20 20 20 20 61 6e 64 20 68 61 76 69          and havi
2a450 6e 67 20 61 20 70 72 65 66 65 72 72 65 64 20 74  ng a preferred t
2a460 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  ext encoding of 
2a470 45 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 30 39  E..**.** {F16109
2a480 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
2a490 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2a4a0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2a4b0 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
2a4c0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  ].**          re
2a4d0 70 6c 61 63 65 73 20 74 68 65 20 50 2c 20 46 2c  places the P, F,
2a4e0 20 53 2c 20 61 6e 64 20 4c 20 76 61 6c 75 65 73   S, and L values
2a4f0 20 66 72 6f 6d 20 61 6e 79 20 70 72 69 6f 72 20   from any prior 
2a500 63 61 6c 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20  calls with.**   
2a510 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20         the same 
2a520 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20 45 20 76  D, X, N, and E v
2a530 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  alues..**.** {F1
2a540 36 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  6112} The [sqlit
2a550 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2a560 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74  on(D,X,...)] int
2a570 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
2a580 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  h.**          a 
2a590 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b  return code of [
2a5a0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
2a5b0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2a5c0 6e 20 6e 61 6d 65 20 58 20 69 73 0a 2a 2a 20 20  n name X is.**  
2a5d0 20 20 20 20 20 20 20 20 6c 6f 6e 67 65 72 20 74          longer t
2a5e0 68 61 6e 20 32 35 35 20 62 79 74 65 73 20 65 78  han 255 bytes ex
2a5f0 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a  clusive of the z
2a600 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
2a610 2a 2a 0a 2a 2a 20 7b 46 31 36 31 31 38 7d 20 45  **.** {F16118} E
2a620 69 74 68 65 72 20 46 20 6d 75 73 74 20 62 65 20  ither F must be 
2a630 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c  NULL and S and L
2a640 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f 72   are non-NULL or
2a650 20 65 6c 73 65 20 46 0a 2a 2a 20 20 20 20 20 20   else F.**      
2a660 20 20 20 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20      is non-NULL 
2a670 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65 20  and S and L are 
2a680 4e 55 4c 4c 2c 20 6f 74 68 65 72 77 69 73 65 0a  NULL, otherwise.
2a690 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2a6a0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2a6b0 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  tion(D,X,N,E,P,F
2a6c0 2c 53 2c 4c 29 5d 20 72 65 74 75 72 6e 73 20 5b  ,S,L)] returns [
2a6d0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 0a 2a  SQLITE_ERROR]..*
2a6e0 2a 0a 2a 2a 20 7b 46 31 36 31 32 31 7d 20 54 68  *.** {F16121} Th
2a6f0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2a700 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 2e 2e 2e  e_function(D,...
2a710 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  )] interface fai
2a720 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20  ls with an.**   
2a730 20 20 20 20 20 20 20 65 72 72 6f 72 20 63 6f 64         error cod
2a740 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42 55 53  e of [SQLITE_BUS
2a750 59 5d 20 69 66 20 74 68 65 72 65 20 65 78 69 73  Y] if there exis
2a760 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  t [prepared stat
2a770 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20 20 20 20 20  ements].**      
2a780 20 20 20 20 61 73 73 6f 63 69 61 74 65 64 20 77      associated w
2a790 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
2a7a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e  e connection] D.
2a7b0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 34 7d 20  .**.** {F16124} 
2a7c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
2a7d0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2a7e0 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  ,N,...)] interfa
2a7f0 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  ce fails with an
2a800 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72 72  .**          err
2a810 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  or code of [SQLI
2a820 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 70 61 72  TE_ERROR] if par
2a830 61 6d 65 74 65 72 20 4e 20 28 73 70 65 63 69 66  ameter N (specif
2a840 79 69 6e 67 20 74 68 65 20 6e 75 6d 62 65 72 0a  ying the number.
2a850 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61  **          of a
2a860 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
2a870 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  SQL function bei
2a880 6e 67 20 72 65 67 69 73 74 65 72 65 64 29 20 69  ng registered) i
2a890 73 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20 20  s less.**       
2a8a0 20 20 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72     than -1 or gr
2a8b0 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 2e 0a  eater than 127..
2a8c0 2a 2a 0a 2a 2a 20 7b 46 31 36 31 32 37 7d 20 57  **.** {F16127} W
2a8d0 68 65 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67  hen N is non-neg
2a8e0 61 74 69 76 65 2c 20 74 68 65 20 5b 73 71 6c 69  ative, the [sqli
2a8f0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2a900 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a  ion(D,X,N,...)].
2a910 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
2a920 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61 6c  rface causes cal
2a930 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76  lbacks to be inv
2a940 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51 4c  oked for the SQL
2a950 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
2a960 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77 68        named X wh
2a970 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  en the number of
2a980 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
2a990 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
2a9a0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78  s.**          ex
2a9b0 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b  actly N..**.** {
2a9c0 46 31 36 31 33 30 7d 20 57 68 65 6e 20 4e 20 69  F16130} When N i
2a9d0 73 20 2d 31 2c 20 74 68 65 20 5b 73 71 6c 69 74  s -1, the [sqlit
2a9e0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2a9f0 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a  on(D,X,N,...)].*
2aa00 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
2aa10 66 61 63 65 20 63 61 75 73 65 73 20 63 61 6c 6c  face causes call
2aa20 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f  backs to be invo
2aa30 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51 4c 20  ked for the SQL 
2aa40 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  function.**     
2aa50 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77 69 74       named X wit
2aa60 68 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  h any number of 
2aa70 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
2aa80 20 7b 46 31 36 31 33 33 7d 20 57 68 65 6e 20 63   {F16133} When c
2aa90 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2aaa0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2aab0 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20  (D,X,N,...)].** 
2aac0 20 20 20 20 20 20 20 20 20 73 70 65 63 69 66 79           specify
2aad0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
2aae0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
2aaf0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58   same function X
2ab00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
2ab10 20 77 68 65 6e 20 6f 6e 65 20 69 6d 70 6c 65 6d   when one implem
2ab20 65 6e 74 61 74 69 6f 6e 20 68 61 73 20 4e 3e 3d  entation has N>=
2ab30 30 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  0 and the other 
2ab40 68 61 73 20 4e 3d 28 2d 31 29 0a 2a 2a 20 20 20  has N=(-1).**   
2ab50 20 20 20 20 20 20 20 74 68 65 20 69 6d 70 6c 65         the imple
2ab60 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
2ab70 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20 69 73 20 70   non-zero N is p
2ab80 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  referred..**.** 
2ab90 7b 46 31 36 31 33 36 7d 20 57 68 65 6e 20 63 61  {F16136} When ca
2aba0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2abb0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2abc0 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a  D,X,N,E,...)].**
2abd0 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69 66            specif
2abe0 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  y multiple imple
2abf0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
2ac00 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2ac10 58 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  X with.**       
2ac20 20 20 20 74 68 65 20 73 61 6d 65 20 6e 75 6d 62     the same numb
2ac30 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2ac40 4e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  N but with diffe
2ac50 72 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  rent.**         
2ac60 20 65 6e 63 6f 64 69 6e 67 73 20 45 2c 20 74 68   encodings E, th
2ac70 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  en the implement
2ac80 61 74 69 6f 6e 20 77 68 65 72 65 20 45 20 6d 61  ation where E ma
2ac90 74 63 68 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  tches the.**    
2aca0 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20 65        database e
2acb0 6e 63 6f 64 69 6e 67 20 69 73 20 70 72 65 66 65  ncoding is prefe
2acc0 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  rred..**.** {F16
2acd0 31 33 39 7d 20 46 6f 72 20 61 6e 20 61 67 67 72  139} For an aggr
2ace0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2acf0 6f 6e 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  on created using
2ad00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2ad10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2ad20 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
2ad30 30 2c 53 2c 4c 29 5d 20 74 68 65 20 66 69 6e 61  0,S,L)] the fina
2ad40 6c 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  lizer.**        
2ad50 20 20 66 75 6e 63 74 69 6f 6e 20 4c 20 77 69 6c    function L wil
2ad60 6c 20 61 6c 77 61 79 73 20 62 65 20 69 6e 76 6f  l always be invo
2ad70 6b 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  ked exactly once
2ad80 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   if the.**      
2ad90 20 20 20 20 73 74 65 70 20 66 75 6e 63 74 69 6f      step functio
2ada0 6e 20 53 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  n S is called on
2adb0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
2adc0 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 31 34 32 7d 20  .**.** {F16142} 
2add0 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
2ade0 6b 65 73 20 65 69 74 68 65 72 20 74 68 65 20 78  kes either the x
2adf0 46 75 6e 63 20 6f 72 20 78 53 74 65 70 20 66 75  Func or xStep fu
2ae00 6e 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20  nction of.**    
2ae10 20 20 20 20 20 20 61 6e 20 61 70 70 6c 69 63 61        an applica
2ae20 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2ae30 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
2ae40 72 65 67 61 74 65 20 63 72 65 61 74 65 64 0a 2a  regate created.*
2ae50 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 5b 73  *          by [s
2ae60 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2ae70 6e 63 74 69 6f 6e 28 29 5d 20 6f 72 20 5b 73 71  nction()] or [sq
2ae80 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2ae90 63 74 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20  ction16()],.**  
2aea0 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65          then the
2aeb0 20 61 72 72 61 79 20 6f 66 20 5b 73 71 6c 69 74   array of [sqlit
2aec0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2aed0 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  s passed as the.
2aee0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 69 72  **          thir
2aef0 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20  d parameter are 
2af00 61 6c 77 61 79 73 20 5b 70 72 6f 74 65 63 74 65  always [protecte
2af10 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2af20 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69 6e 74   objects..*/.int
2af30 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2af40 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
2af50 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
2af60 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
2af70 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
2af80 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2af90 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
2afa0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
2afb0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2afc0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2afd0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2afe0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
2aff0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2b000 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2b010 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
2b020 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2b030 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2b040 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2b050 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
2b060 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
2b070 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
2b080 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
2b090 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
2b0a0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
2b0b0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
2b0c0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2b0d0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2b0e0 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
2b0f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2b100 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2b110 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2b120 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
2b130 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a  context*).);../*
2b140 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
2b150 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b 46 31  xt Encodings {F1
2b160 30 32 36 37 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0267}.**.** Thes
2b170 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  e constant defin
2b180 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20  e integer codes 
2b190 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74  that represent t
2b1a0 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65  he various.** te
2b1b0 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70  xt encodings sup
2b1c0 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
2b1d0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
2b1e0 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20  ITE_UTF8        
2b1f0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
2b200 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20  ITE_UTF16LE     
2b210 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2b220 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
2b230 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
2b240 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20  ITE_UTF16       
2b250 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e     4    /* Use n
2b260 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2b270 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2b280 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20  TE_ANY          
2b290 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    5    /* sqlite
2b2a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2b2b0 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  n only */.#defin
2b2c0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
2b2d0 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
2b2e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2b2f0 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
2b300 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b310 3a 20 4f 62 73 6f 6c 65 74 65 20 46 75 6e 63 74  : Obsolete Funct
2b320 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
2b330 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61   functions are a
2b340 6c 6c 20 6e 6f 77 20 6f 62 73 6f 6c 65 74 65 2e  ll now obsolete.
2b350 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
2b360 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
2b370 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
2b380 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
2b390 65 2c 20 77 65 20 63 6f 6e 74 69 6e 75 65 20 74  e, we continue t
2b3a0 6f 20 73 75 70 70 6f 72 74 0a 2a 2a 20 74 68 65  o support.** the
2b3b0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 48  se functions.  H
2b3c0 6f 77 65 76 65 72 2c 20 6e 65 77 20 64 65 76 65  owever, new deve
2b3d0 6c 6f 70 6d 65 6e 74 20 70 72 6f 6a 65 63 74 73  lopment projects
2b3e0 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a   should avoid.**
2b3f0 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73   the use of thes
2b400 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f  e functions.  To
2b410 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20   help encourage 
2b420 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a  people to avoid.
2b430 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66  ** using these f
2b440 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65  unctions, we are
2b450 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65   not going to te
2b460 6c 6c 20 79 6f 75 20 77 61 6e 74 20 74 68 65 79  ll you want they
2b470 20 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69   do..*/.int sqli
2b480 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2b490 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
2b4a0 65 78 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  ext*);.int sqlit
2b4b0 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74  e3_expired(sqlit
2b4c0 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73  e3_stmt*);.int s
2b4d0 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f  qlite3_transfer_
2b4e0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
2b4f0 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f  _stmt*, sqlite3_
2b500 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  stmt*);.int sqli
2b510 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
2b520 65 72 28 76 6f 69 64 29 3b 0a 76 6f 69 64 20 73  er(void);.void s
2b530 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c  qlite3_thread_cl
2b540 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 69 6e 74  eanup(void);.int
2b550 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
2b560 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f  alarm(void(*)(vo
2b570 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
2b580 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c  4,int),void*,sql
2b590 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a  ite3_int64);../*
2b5a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
2b5b0 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63  taining SQL Func
2b5c0 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56  tion Parameter V
2b5d0 61 6c 75 65 73 20 7b 46 31 35 31 30 30 7d 0a 2a  alues {F15100}.*
2b5e0 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75  *.** The C-langu
2b5f0 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  age implementati
2b600 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69  on of SQL functi
2b610 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
2b620 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20  es uses.** this 
2b630 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65  set of interface
2b640 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63   routines to acc
2b650 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65  ess the paramete
2b660 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74  r values on.** t
2b670 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  he function or a
2b680 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ggregate..**.** 
2b690 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73  The xFunc (for s
2b6a0 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29  calar functions)
2b6b0 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61   or xStep (for a
2b6c0 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d  ggregates) param
2b6d0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c  eters.** to [sql
2b6e0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2b6f0 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
2b700 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2b710 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66  tion16()].** def
2b720 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  ine callbacks th
2b730 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
2b740 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
2b750 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a  nd aggregates..*
2b760 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65  * The 4th parame
2b770 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c  ter to these cal
2b780 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72  lbacks is an arr
2b790 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
2b7a0 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20  o.** [protected 
2b7b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2b7c0 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69  bjects.  There i
2b7d0 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76  s one [sqlite3_v
2b7e0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
2b7f0 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74  .** each paramet
2b800 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  er to the SQL fu
2b810 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72  nction.  These r
2b820 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
2b830 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76   to.** extract v
2b840 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  alues from the [
2b850 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2b860 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  bjects..**.** Th
2b870 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
2b880 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f  k only with [pro
2b890 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2b8a0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
2b8b0 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
2b8c0 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69   use these routi
2b8d0 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f  nes on an [unpro
2b8e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2b8f0 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  alue].** object 
2b900 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
2b910 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
2b920 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2b930 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
2b940 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
2b950 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63  ding [column acc
2b960 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a  ess functions].*
2b970 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74  * except that  t
2b980 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
2b990 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
2b9a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2b9b0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
2b9c0 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
2b9d0 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
2b9e0 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
2b9f0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
2ba00 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
2ba10 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
2ba20 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
2ba30 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
2ba40 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
2ba50 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
2ba60 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
2ba70 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
2ba80 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
2ba90 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
2baa0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c   and sqlite3_val
2bab0 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e  ue_text16le() in
2bac0 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72  terfaces.** extr
2bad0 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e  act UTF-16 strin
2bae0 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e  gs as big-endian
2baf0 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69   and little-endi
2bb00 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  an respectively.
2bb10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2bb20 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
2bb30 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
2bb40 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
2bb50 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
2bb60 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
2bb70 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
2bb80 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
2bb90 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
2bba0 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
2bbb0 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
2bbc0 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
2bbd0 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
2bbe0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
2bbf0 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
2bc00 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
2bc10 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
2bc20 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76   words, if the v
2bc30 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67  alue is a string
2bc40 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
2bc50 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
2bc60 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  en the conversio
2bc70 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20  n is performed. 
2bc80 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
2bc90 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
2bca0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
2bcb0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
2bcc0 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
2bcd0 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
2bce0 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ..**.** Please p
2bcf0 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
2bd00 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
2bd10 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
2bd20 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
2bd30 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
2bd40 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
2bd50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2bd60 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
2bd70 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2bd80 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
2bd90 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
2bda0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
2bdb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2bdc0 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
2bdd0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2bde0 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
2bdf0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
2be00 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
2be10 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
2be20 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2be30 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
2be40 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2be50 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
2be60 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
2be70 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
2be80 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
2be90 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a  ] parameters..**
2bea0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2beb0 2a 2a 0a 2a 2a 20 7b 46 31 35 31 30 33 7d 20 54  **.** {F15103} T
2bec0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2bed0 65 5f 62 6c 6f 62 28 56 29 5d 20 69 6e 74 65 72  e_blob(V)] inter
2bee0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2bef0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2bf00 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2bf10 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2bf20 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 61 6e 64   into a BLOB and
2bf30 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
2bf40 20 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e    returns a poin
2bf50 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 65  ter to the conve
2bf60 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  rted value..**.*
2bf70 2a 20 7b 46 31 35 31 30 36 7d 20 54 68 65 20 5b  * {F15106} The [
2bf80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2bf90 74 65 73 28 56 29 5d 20 69 6e 74 65 72 66 61 63  tes(V)] interfac
2bfa0 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
2bfb0 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
2bfc0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2bfd0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
2bfe0 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68  (exclusive of th
2bff0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  e.**          ze
2c000 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e  ro terminator on
2c010 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61   the string) tha
2c020 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62  t was returned b
2c030 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  y the.**        
2c040 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61    most recent ca
2c050 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76  ll to [sqlite3_v
2c060 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 6f 72  alue_blob(V)] or
2c070 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2c080 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2c090 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35  (V)]..**.** {F15
2c0a0 31 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  109} The [sqlite
2c0b0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
2c0c0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  V)] interface re
2c0d0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
2c0e0 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
2c0f0 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
2c100 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f  ing (exclusive o
2c110 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2c120 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f    zero terminato
2c130 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29  r on the string)
2c140 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
2c150 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
2c160 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e        most recen
2c170 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2c180 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2c190 56 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  V)],.**         
2c1a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2c1b0 74 65 78 74 31 36 62 65 28 56 29 5d 2c 20 6f 72  text16be(V)], or
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 6c 65 28 56 29 5d 2e 0a 2a 2a  text16le(V)]..**
2c1e0 0a 2a 2a 20 7b 46 31 35 31 31 32 7d 20 54 68 65  .** {F15112} The
2c1f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2c200 64 6f 75 62 6c 65 28 56 29 5d 20 69 6e 74 65 72  double(V)] inter
2c210 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2c220 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2c230 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2c240 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2c250 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67   into a floating
2c260 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e 64   point value and
2c270 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2c280 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  urns a copy of t
2c290 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  hat value..**.**
2c2a0 20 7b 46 31 35 31 31 35 7d 20 54 68 65 20 5b 73   {F15115} The [s
2c2b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2c2c0 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
2c2d0 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2c2e0 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
2c2f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2c300 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
2c310 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  a 64-bit signed 
2c320 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20  integer and.**  
2c330 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
2c340 74 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74  the lower 32 bit
2c350 73 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65  s of that intege
2c360 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 31 38  r..**.** {F15118
2c370 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2c380 61 6c 75 65 5f 69 6e 74 36 34 28 56 29 5d 20 69  alue_int64(V)] i
2c390 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2c3a0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2c3b0 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2c3c0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2c3d0 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62  ct V into a 64-b
2c3e0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2c3f0 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  r and.**        
2c400 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79    returns a copy
2c410 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
2c420 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32 31 7d  ..**.** {F15121}
2c430 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2c440 6c 75 65 5f 74 65 78 74 28 56 29 5d 20 69 6e 74  lue_text(V)] int
2c450 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2c460 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2c470 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2c480 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2c490 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   V into a zero-t
2c4a0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
2c4b0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
2c4c0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
2c4d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
2c4e0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
2c4f0 46 31 35 31 32 34 7d 20 54 68 65 20 5b 73 71 6c  F15124} The [sql
2c500 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2c510 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  6(V)] interface 
2c520 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2c530 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
2c540 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2c550 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
2c560 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2c570 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20  ed 2-byte.**    
2c580 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54        aligned UT
2c590 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
2c5a0 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20   order.**       
2c5b0 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65     string and re
2c5c0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2c5d0 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
2c5e0 2a 2a 0a 2a 2a 20 7b 46 31 35 31 32 37 7d 20 54  **.** {F15127} T
2c5f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2c600 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d 20 69  e_text16be(V)] i
2c610 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2c620 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2c630 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2c640 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2c650 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f  ct V into a zero
2c660 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79  -terminated 2-by
2c670 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  te.**          a
2c680 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 62 69  ligned UTF-16 bi
2c690 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20  g-endian.**     
2c6a0 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20       string and 
2c6b0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2c6c0 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67  r to that string
2c6d0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33 30 7d  ..**.** {F15130}
2c6e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2c6f0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d  lue_text16le(V)]
2c700 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2c710 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2c720 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
2c730 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2c740 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65  ject V into a ze
2c750 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d  ro-terminated 2-
2c760 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  byte.**         
2c770 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20   aligned UTF-16 
2c780 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a  little-endian.**
2c790 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
2c7a0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
2c7b0 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
2c7c0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  tring..**.** {F1
2c7d0 35 31 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  5133} The [sqlit
2c7e0 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 56 29  e3_value_type(V)
2c7f0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
2c800 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
2c810 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e  one of [SQLITE_N
2c820 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e  ULL], [SQLITE_IN
2c830 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f  TEGER], [SQLITE_
2c840 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20  FLOAT],.**      
2c850 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54      [SQLITE_TEXT
2c860 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c  ], or [SQLITE_BL
2c870 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61  OB] as appropria
2c880 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  te for.**       
2c890 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f     the [sqlite3_
2c8a0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 2e  value] object V.
2c8b0 0a 2a 2a 0a 2a 2a 20 7b 46 31 35 31 33 36 7d 20  .**.** {F15136} 
2c8c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2c8d0 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
2c8e0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
2c8f0 6e 76 65 72 74 73 0a 2a 2a 20 20 20 20 20 20 20  nverts.**       
2c900 20 20 20 74 68 65 20 5b 70 72 6f 74 65 63 74 65     the [protecte
2c910 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2c920 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 65   object V into e
2c930 69 74 68 65 72 20 61 6e 20 69 6e 74 65 67 65 72  ither an integer
2c940 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
2c950 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
2c960 20 76 61 6c 75 65 20 69 66 20 69 74 20 63 61 6e   value if it can
2c970 20 64 6f 20 73 6f 20 77 69 74 68 6f 75 74 20 6c   do so without l
2c980 6f 73 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  oss of.**       
2c990 20 20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20     information, 
2c9a0 61 6e 64 20 72 65 74 75 72 6e 73 20 6f 6e 65 20  and returns one 
2c9b0 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  of [SQLITE_NULL]
2c9c0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  ,.**          [S
2c9d0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20  QLITE_INTEGER], 
2c9e0 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
2c9f0 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f  [SQLITE_TEXT], o
2ca00 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  r.**          [S
2ca10 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61  QLITE_BLOB] as a
2ca20 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74  ppropriate for t
2ca30 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2ca40 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2ca50 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2ca60 56 20 61 66 74 65 72 20 74 68 65 20 63 6f 6e 76  V after the conv
2ca70 65 72 73 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a  ersion attempt..
2ca80 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
2ca90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
2caa0 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  b(sqlite3_value*
2cab0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
2cac0 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
2cad0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
2cae0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2caf0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
2cb00 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71  lue*);.double sq
2cb10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
2cb20 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
2cb30 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2cb40 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
2cb50 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74  3_value*);.sqlit
2cb60 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
2cb70 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
2cb80 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
2cb90 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
2cba0 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
2cbb0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
2cbc0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
2cbd0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
2cbe0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
2cbf0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
2cc00 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2cc10 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
2cc20 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
2cc30 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2cc40 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
2cc50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2cc60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
2cc70 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
2cc80 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2cc90 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
2cca0 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ic_type(sqlite3_
2ccb0 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
2ccc0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
2ccd0 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
2cce0 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 46 31 36  ion Context {F16
2ccf0 32 31 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  210}.**.** The i
2cd00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2cd10 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
2cd20 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
2cd30 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c  s routine to all
2cd40 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72 75 63  ocate.** a struc
2cd50 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69 6e 67  ture for storing
2cd60 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a   their state..**
2cd70 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69  .** The first ti
2cd80 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61  me the sqlite3_a
2cd90 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2cda0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
2cdb0 6c 6c 65 64 20 66 6f 72 20 61 0a 2a 2a 20 70 61  lled for a.** pa
2cdc0 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
2cdd0 74 65 2c 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63  te, SQLite alloc
2cde0 61 74 65 73 20 6e 42 79 74 65 73 20 6f 66 20 6d  ates nBytes of m
2cdf0 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75  emory, zeroes ou
2ce00 74 20 74 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79  t that.** memory
2ce10 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  , and returns a 
2ce20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 4f  pointer to it. O
2ce30 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  n second and sub
2ce40 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
2ce50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
2ce60 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
2ce70 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67  for the same agg
2ce80 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
2ce90 69 6e 64 65 78 2c 0a 2a 2a 20 74 68 65 20 73 61  index,.** the sa
2cea0 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74  me buffer is ret
2ceb0 75 72 6e 65 64 2e 20 54 68 65 20 69 6d 70 6c 65  urned. The imple
2cec0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
2ced0 20 61 67 67 72 65 67 61 74 65 20 63 61 6e 20 75   aggregate can u
2cee0 73 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  se.** the return
2cef0 65 64 20 62 75 66 66 65 72 20 74 6f 20 61 63 63  ed buffer to acc
2cf00 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a  umulate data..**
2cf10 0a 2a 2a 20 53 51 4c 69 74 65 20 61 75 74 6f 6d  .** SQLite autom
2cf20 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
2cf30 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 75 66  he allocated buf
2cf40 66 65 72 20 77 68 65 6e 20 74 68 65 20 61 67 67  fer when the agg
2cf50 72 65 67 61 74 65 0a 2a 2a 20 71 75 65 72 79 20  regate.** query 
2cf60 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
2cf70 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
2cf80 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61  eter should be a
2cf90 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
2cfa0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
2cfb0 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20   | SQL function 
2cfc0 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73  context] that is
2cfd0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
2cfe0 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
2cff0 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
2d000 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
2d010 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
2d020 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
2d030 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
2d040 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
2d050 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
2d060 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
2d070 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
2d080 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
2d090 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2d0a0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31  TS:.**.** {F1621
2d0b0 31 7d 20 54 68 65 20 66 69 72 73 74 20 69 6e 76  1} The first inv
2d0c0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
2d0d0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2d0e0 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 0a  ntext(C,N)] for.
2d0f0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 61  **          a pa
2d100 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63  rticular instanc
2d110 65 20 6f 66 20 61 6e 20 61 67 67 72 65 67 61 74  e of an aggregat
2d120 65 20 66 75 6e 63 74 69 6f 6e 20 28 66 6f 72 20  e function (for 
2d130 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
2d140 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74           context
2d150 20 43 29 20 63 61 75 73 65 73 20 53 51 4c 69 74   C) causes SQLit
2d160 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 4e 20  e to allocate N 
2d170 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c  bytes of memory,
2d180 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
2d190 6f 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61  o that memory, a
2d1a0 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e  nd return a poin
2d1b0 74 65 72 20 74 6f 20 74 68 65 20 61 6c 6c 6f 63  ter to the alloc
2d1c0 61 74 65 64 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a  ated memory..**.
2d1d0 2a 2a 20 7b 46 31 36 32 31 33 7d 20 49 66 20 61  ** {F16213} If a
2d1e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2d1f0 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
2d200 64 75 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  during.**       
2d210 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72     [sqlite3_aggr
2d220 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
2d230 4e 29 5d 20 74 68 65 6e 20 74 68 65 20 66 75 6e  N)] then the fun
2d240 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 2e  ction returns 0.
2d250 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 35 7d 20  .**.** {F16215} 
2d260 53 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  Second and subse
2d270 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
2d280 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  s of.**         
2d290 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
2d2a0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
2d2b0 5d 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 63  ] for the same c
2d2c0 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 43  ontext pointer C
2d2d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 67 6e  .**          ign
2d2e0 6f 72 65 20 74 68 65 20 4e 20 70 61 72 61 6d 65  ore the N parame
2d2f0 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 20 61  ter and return a
2d300 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2d310 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
2d320 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
2d330 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2d340 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f   first invocatio
2d350 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 31 37  n..**.** {F16217
2d360 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  } The memory all
2d370 6f 63 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74  ocated by [sqlit
2d380 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2d390 74 65 78 74 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a  text(C,N)] is.**
2d3a0 20 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d 61            automa
2d3b0 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20 6f 6e  tically freed on
2d3c0 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74   the next call t
2d3d0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
2d3e0 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
2d3f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2d400 6c 69 7a 65 28 29 5d 20 66 6f 72 20 74 68 65 20  lize()] for the 
2d410 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d420 65 6e 74 5d 20 63 6f 6e 74 61 69 6e 69 6e 67 0a  ent] containing.
2d430 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2d440 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
2d450 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  on associated wi
2d460 74 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f  th context C..*/
2d470 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61  .void *sqlite3_a
2d480 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2d490 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2d4a0 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a  *, int nBytes);.
2d4b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d4c0 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46   User Data For F
2d4d0 75 6e 63 74 69 6f 6e 73 20 7b 46 31 36 32 34 30  unctions {F16240
2d4e0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
2d4f0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20  te3_user_data() 
2d500 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2d510 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
2d520 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  he pointer that 
2d530 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74  was the pUserDat
2d540 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65  a parameter (the
2d550 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a   5th parameter).
2d560 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
2d570 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2d580 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
2d590 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2d5a0 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
2d5b0 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
2d5c0 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
2d5d0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
2d5e0 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
2d5f0 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  on. {END}.**.** 
2d600 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
2d610 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
2d620 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2d630 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
2d640 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2d650 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
2d660 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   running..**.** 
2d670 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2d680 2a 20 7b 46 31 36 32 34 33 7d 20 54 68 65 20 5b  * {F16243} The [
2d690 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2d6a0 61 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20  a(C)] interface 
2d6b0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2d6c0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2d6d0 20 20 50 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d    P pointer from
2d6e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
2d6f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2d700 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a  X,N,E,P,F,S,L)].
2d710 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b  **          or [
2d720 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2d730 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c  unction16(D,X,N,
2d740 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c  E,P,F,S,L)] call
2d750 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20   that.**        
2d760 20 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65    registered the
2d770 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73   SQL function as
2d780 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b 73  sociated with [s
2d790 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
2d7a0 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  C..*/.void *sqli
2d7b0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
2d7c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2d7d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d7e0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
2d7f0 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69  ction For Functi
2d800 6f 6e 73 20 7b 46 31 36 32 35 30 7d 0a 2a 2a 0a  ons {F16250}.**.
2d810 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
2d820 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
2d830 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2d840 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
2d850 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f  * the pointer to
2d860 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2d870 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20  onnection] (the 
2d880 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  1st parameter).*
2d890 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
2d8a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2d8b0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
2d8c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2d8d0 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
2d8e0 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
2d8f0 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
2d900 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2d910 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
2d920 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  n..**.** INVARIA
2d930 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  NTS:.**.** {F162
2d940 35 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  53} The [sqlite3
2d950 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
2d960 6c 65 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  le(C)] interface
2d970 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
2d980 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
2d990 20 20 20 44 20 70 6f 69 6e 74 65 72 20 66 72 6f     D pointer fro
2d9a0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  m the [sqlite3_c
2d9b0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2d9c0 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d  ,X,N,E,P,F,S,L)]
2d9d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
2d9e0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2d9f0 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e  function16(D,X,N
2da00 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c  ,E,P,F,S,L)] cal
2da10 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20  l that.**       
2da20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74 68     registered th
2da30 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61  e SQL function a
2da40 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b  ssociated with [
2da50 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
2da60 20 43 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a   C..*/.sqlite3 *
2da70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
2da80 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
2da90 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
2daa0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
2dab0 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79  nction Auxiliary
2dac0 20 44 61 74 61 20 7b 46 31 36 32 37 30 7d 0a 2a   Data {F16270}.*
2dad0 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
2dae0 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  ng two functions
2daf0 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
2db00 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
2db10 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
2db20 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
2db30 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
2db40 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
2db50 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
2db60 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
2db70 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
2db80 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
2db90 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
2dba0 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
2dbb0 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
2dbc0 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
2dbd0 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
2dbe0 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
2dbf0 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65  . This may.** be
2dc00 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70   used, for examp
2dc10 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67  le, to add a reg
2dc20 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
2dc30 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a  matching scalar.
2dc40 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
2dc50 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
2dc60 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
2dc70 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73   expression is s
2dc80 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61  tored as.** meta
2dc90 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
2dca0 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c  with the SQL val
2dcb0 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
2dcc0 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
2dcd0 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20  ion.** pattern. 
2dce0 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   The compiled re
2dcf0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
2dd00 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
2dd10 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
2dd20 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
2dd30 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73   same function s
2dd40 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69  o that the origi
2dd50 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69  nal pattern stri
2dd60 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e  ng.** does not n
2dd70 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70  eed to be recomp
2dd80 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76  iled on each inv
2dd90 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  ocation..**.** T
2dda0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
2ddb0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
2ddc0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2ddd0 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
2dde0 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
2ddf0 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
2de00 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
2de10 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68  function with th
2de20 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  e Nth argument.*
2de30 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61  * value to the a
2de40 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2de50 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20  ed function. If 
2de60 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  no metadata has 
2de70 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65  been ever.** bee
2de80 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74  n set for the Nt
2de90 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  h argument of th
2dea0 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69  e function, or i
2deb0 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
2dec0 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
2ded0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68  parameter has ch
2dee0 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20  anged since the 
2def0 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65  meta-data was se
2df00 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  t,.** then sqlit
2df10 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
2df20 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
2df30 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
2df40 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
2df50 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
2df60 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74  ce saves the met
2df70 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64  adata.** pointed
2df80 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70   to by its 3rd p
2df90 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
2dfa0 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
2dfb0 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
2dfc0 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
2dfd0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2dfe0 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65  ction.  Subseque
2dff0 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
2e000 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2e010 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72  ta() might retur
2e020 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20  n this data, if 
2e030 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65  it has.** not be
2e040 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  en destroyed..**
2e050 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55   If it is not NU
2e060 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  LL, SQLite will 
2e070 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
2e080 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  uctor.** functio
2e090 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34  n given by the 4
2e0a0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2e0b0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2e0c0 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20  ata() on.** the 
2e0d0 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68  metadata when th
2e0e0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2e0f0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
2e100 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72  er changes.** or
2e110 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   when the SQL st
2e120 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65  atement complete
2e130 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  s, whichever com
2e140 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20  es first..**.** 
2e150 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
2e160 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72  o call the destr
2e170 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d  uctor and drop m
2e180 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a  etadata on any.*
2e190 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61  * parameter of a
2e1a0 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61  ny function at a
2e1b0 6e 79 20 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e  ny time.  The on
2e1c0 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20  ly guarantee is 
2e1d0 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74  that.** the dest
2e1e0 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63  ructor will be c
2e1f0 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65  alled before the
2e200 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f   metadata is dro
2e210 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70  pped..**.** In p
2e220 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74  ractice, metadat
2e230 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62  a is preserved b
2e240 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20  etween function 
2e250 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70  calls for.** exp
2e260 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72  ressions that ar
2e270 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f  e constant at co
2e280 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73  mpile time. This
2e290 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61   includes litera
2e2a0 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20  l.** values and 
2e2b0 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a  SQL variables..*
2e2c0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2e2d0 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
2e2e0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2e2f0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2e300 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
2e310 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
2e320 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
2e330 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 32  S:.**.** {F16272
2e340 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67  } The [sqlite3_g
2e350 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 5d  et_auxdata(C,N)]
2e360 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2e370 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
2e380 20 20 20 20 20 20 20 20 20 74 6f 20 6d 65 74 61           to meta
2e390 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
2e3a0 77 69 74 68 20 74 68 65 20 4e 74 68 20 70 61 72  with the Nth par
2e3b0 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51  ameter of the SQ
2e3c0 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  L function.**   
2e3d0 20 20 20 20 20 20 20 77 68 6f 73 65 20 63 6f 6e         whose con
2e3e0 74 65 78 74 20 69 73 20 43 2c 20 6f 72 20 4e 55  text is C, or NU
2e3f0 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e  LL if there is n
2e400 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  o metadata assoc
2e410 69 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  iated.**        
2e420 20 20 77 69 74 68 20 74 68 61 74 20 70 61 72 61    with that para
2e430 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  meter..**.** {F1
2e440 36 32 37 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  6274} The [sqlit
2e450 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
2e460 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,N,P,D)] interfa
2e470 63 65 20 61 73 73 69 67 6e 73 20 61 20 6d 65 74  ce assigns a met
2e480 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20  adata.**        
2e490 20 20 70 6f 69 6e 74 65 72 20 50 20 74 6f 20 74    pointer P to t
2e4a0 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72  he Nth parameter
2e4b0 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
2e4c0 74 69 6f 6e 20 77 69 74 68 20 63 6f 6e 74 65 78  tion with contex
2e4d0 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  t C..**.** {F162
2e4e0 37 36 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  76} SQLite will 
2e4f0 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
2e500 75 63 74 6f 72 20 44 20 77 69 74 68 20 61 20 73  uctor D with a s
2e510 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ingle argument.*
2e520 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 63 68  *          which
2e530 20 69 73 20 74 68 65 20 6d 65 74 61 64 61 74 61   is the metadata
2e540 20 70 6f 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f   pointer P follo
2e550 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  wing a call to.*
2e560 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2e570 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2e580 43 2c 4e 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53  C,N,P,D)] when S
2e590 51 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20  QLite ceases to 
2e5a0 68 6f 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  hold.**         
2e5b0 20 74 68 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a   the metadata..*
2e5c0 2a 0a 2a 2a 20 7b 46 31 36 32 37 37 7d 20 53 51  *.** {F16277} SQ
2e5d0 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68  Lite ceases to h
2e5e0 6f 6c 64 20 6d 65 74 61 64 61 74 61 20 66 6f 72  old metadata for
2e5f0 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
2e600 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
2e610 20 20 20 20 20 20 20 77 68 65 6e 20 74 68 65 20         when the 
2e620 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 70 61  value of that pa
2e630 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2e  rameter changes.
2e640 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32 37 38 7d 20  .**.** {F16278} 
2e650 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65  When [sqlite3_se
2e660 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
2e670 44 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  D)] is invoked, 
2e680 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
2e690 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 63 61  *          is ca
2e6a0 6c 6c 65 64 20 66 6f 72 20 61 6e 79 20 70 72 69  lled for any pri
2e6b0 6f 72 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  or metadata asso
2e6c0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2e6d0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  same function.**
2e6e0 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78            contex
2e6f0 74 20 43 20 61 6e 64 20 70 61 72 61 6d 65 74 65  t C and paramete
2e700 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 32  r N..**.** {F162
2e710 37 39 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  79} SQLite will 
2e720 63 61 6c 6c 20 64 65 73 74 72 75 63 74 6f 72 73  call destructors
2e730 20 66 6f 72 20 61 6e 79 20 6d 65 74 61 64 61 74   for any metadat
2e740 61 20 69 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a  a it is holding.
2e750 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 61  **          in a
2e760 20 70 61 72 74 69 63 75 6c 61 72 20 5b 70 72 65   particular [pre
2e770 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2e780 20 53 20 77 68 65 6e 20 65 69 74 68 65 72 0a 2a   S when either.*
2e790 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2e7a0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 6f 72  te3_reset(S)] or
2e7b0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2e7c0 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64  ze(S)] is called
2e7d0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
2e7e0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
2e7f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2e800 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71   int N);.void sq
2e810 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2e820 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
2e830 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a  t*, int N, void*
2e840 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a  , void (*)(void*
2e850 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ));.../*.** CAPI
2e860 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20  3REF: Constants 
2e870 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c  Defining Special
2e880 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61   Destructor Beha
2e890 76 69 6f 72 20 7b 46 31 30 32 38 30 7d 0a 2a 2a  vior {F10280}.**
2e8a0 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70  .** These are sp
2e8b0 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72  ecial values for
2e8c0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
2e8d0 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69  that is passed i
2e8e0 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61  n as the.** fina
2e8f0 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f  l argument to ro
2e900 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
2e910 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2e920 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73  ()].  If the des
2e930 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
2e940 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
2e950 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
2e960 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
2e970 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
2e980 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
2e990 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
2e9a0 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
2e9b0 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
2e9c0 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f    The.** SQLITE_
2e9d0 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20  TRANSIENT value 
2e9e0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
2e9f0 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65  ontent will like
2ea00 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ly change in.** 
2ea10 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20  the near future 
2ea20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20  and that SQLite 
2ea30 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20  should make its 
2ea40 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
2ea50 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
2ea60 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  nt before return
2ea70 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ing..**.** The t
2ea80 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73  ypedef is necess
2ea90 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ary to work arou
2eaa0 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63  nd problems in c
2eab0 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f  ertain.** C++ co
2eac0 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69  mpilers.  See ti
2ead0 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74  cket #2191..*/.t
2eae0 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
2eaf0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
2eb00 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23  _type)(void*);.#
2eb10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
2eb20 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69  ATIC      ((sqli
2eb30 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
2eb40 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53  ype)0).#define S
2eb50 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
2eb60 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
2eb70 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a  ructor_type)-1).
2eb80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2eb90 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73   Setting The Res
2eba0 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ult Of An SQL Fu
2ebb0 6e 63 74 69 6f 6e 20 7b 46 31 36 34 30 30 7d 0a  nction {F16400}.
2ebc0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2ebd0 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79  ines are used by
2ebe0 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46   the xFunc or xF
2ebf0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74  inal callbacks t
2ec00 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  hat.** implement
2ec10 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
2ec20 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  nd aggregates.  
2ec30 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  See.** [sqlite3_
2ec40 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2ec50 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2ec60 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2ec70 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69  6()].** for addi
2ec80 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
2ec90 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  on..**.** These 
2eca0 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76  functions work v
2ecb0 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68  ery much like th
2ecc0 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  e [parameter bin
2ecd0 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  ding] family of.
2ece0 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  ** functions use
2ecf0 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73  d to bind values
2ed00 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74   to host paramet
2ed10 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20  ers in prepared 
2ed20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52  statements..** R
2ed30 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c  efer to the [SQL
2ed40 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75   parameter] docu
2ed50 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
2ed60 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
2ed70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
2ed80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2ed90 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20  lob() interface 
2eda0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
2edb0 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
2edc0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2edd0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
2ede0 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e  e BLOB whose con
2edf0 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a  tent is pointed.
2ee00 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ** to by the sec
2ee10 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  ond parameter an
2ee20 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74  d which is N byt
2ee30 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20  es long where N 
2ee40 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20  is the.** third 
2ee50 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
2ee60 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2ee70 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69  ult_zeroblob() i
2ee80 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68  nterfaces set th
2ee90 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
2eea0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2eeb0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2eec0 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e  to be a BLOB con
2eed0 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f  taining all zero
2eee0 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20  .** bytes and N 
2eef0 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77  bytes in size, w
2ef00 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61  here N is the va
2ef10 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70  lue of the 2nd p
2ef20 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
2ef30 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2ef40 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65  lt_double() inte
2ef50 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2ef60 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
2ef70 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2ef80 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2ef90 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70   be a floating p
2efa0 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69  oint value speci
2efb0 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32  fied.** by its 2
2efc0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
2efd0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2efe0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
2eff0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2f000 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74  _error16() funct
2f010 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68  ions.** cause th
2f020 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51  e implemented SQ
2f030 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68  L function to th
2f040 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  row an exception
2f050 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  ..** SQLite uses
2f060 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e   the string poin
2f070 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a  ted to by the.**
2f080 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
2f090 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  f sqlite3_result
2f0a0 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69  _error() or sqli
2f0b0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2f0c0 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74  16().** as the t
2f0d0 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ext of an error 
2f0e0 6d 65 73 73 61 67 65 2e 20 20 53 51 4c 69 74 65  message.  SQLite
2f0f0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
2f100 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
2f110 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
2f120 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2f130 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 53 51  r() as UTF-8. SQ
2f140 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  Lite.** interpre
2f150 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72  ts the string fr
2f160 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
2f170 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55  t_error16() as U
2f180 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a  TF-16 in native.
2f190 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20  ** byte order.  
2f1a0 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
2f1b0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2f1c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2f1d0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
2f1e0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
2f1f0 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
2f200 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
2f210 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
2f220 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
2f230 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
2f240 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
2f250 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74 68  er..** If the th
2f260 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
2f270 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f280 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
2f290 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2f2a0 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
2f2b0 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
2f2c0 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
2f2d0 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
2f2e0 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
2f2f0 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
2f300 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
2f310 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65   message..** The
2f320 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f330 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
2f340 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2f350 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  16().** routines
2f360 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20   make a private 
2f370 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f  copy of the erro
2f380 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62  r message text b
2f390 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65  efore.** they re
2f3a0 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68  turn.  Hence, th
2f3b0 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
2f3c0 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74  on can deallocat
2f3d0 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74  e or.** modify t
2f3e0 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68  he text after th
2f3f0 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75  ey return withou
2f400 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73  t harm..** The s
2f410 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2f420 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
2f430 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
2f440 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
2f450 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
2f460 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
2f470 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
2f480 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64 65 66 61  nction.  By defa
2f490 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f  ult,.** the erro
2f4a0 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45  r code is SQLITE
2f4b0 5f 45 52 52 4f 52 2e 20 20 41 20 73 75 62 73 65  _ERROR.  A subse
2f4c0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
2f4d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2f4e0 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
2f4f0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2f500 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
2f510 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
2f520 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
2f530 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2f540 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74  ult_toobig() int
2f550 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
2f560 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
2f570 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
2f580 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69  ting that a stri
2f590 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f  ng or BLOB is to
2f5a0 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65   long to represe
2f5b0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  nt..**.** The sq
2f5c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d  lite3_result_nom
2f5d0 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  em() interface c
2f5e0 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
2f5f0 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a  throw an error.*
2f600 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  * indicating tha
2f610 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  t a memory alloc
2f620 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a  ation failed..**
2f630 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2f640 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74  result_int() int
2f650 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
2f660 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
2f670 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2f680 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2f690 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32  ion to be the 32
2f6a0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2f6b0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
2f6c0 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
2f6d0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73  gument..** The s
2f6e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
2f6f0 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
2f700 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
2f710 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
2f720 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2f730 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2f740 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69  be the 64-bit si
2f750 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
2f760 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
2f770 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
2f780 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2f790 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29  e3_result_null()
2f7a0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
2f7b0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2f7c0 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
2f7d0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2f7e0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55  unction to be NU
2f7f0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  LL..**.** The sq
2f800 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2f810 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73  t(), sqlite3_res
2f820 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  ult_text16(),.**
2f830 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f840 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20  text16le(), and 
2f850 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2f860 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66  ext16be() interf
2f870 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20  aces.** set the 
2f880 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
2f890 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2f8a0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2f8b0 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74   to be.** a text
2f8c0 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
2f8d0 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20   represented as 
2f8e0 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61  UTF-8, UTF-16 na
2f8f0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c  tive byte order,
2f900 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
2f910 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46  e endian, or UTF
2f920 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20  -16 big endian, 
2f930 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
2f940 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68   SQLite takes th
2f950 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
2f960 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
2f970 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
2f980 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
2f990 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2f9a0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2f9b0 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33  ces..** If the 3
2f9c0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2f9d0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2f9e0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2f9f0 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
2fa00 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
2fa10 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
2fa20 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
2fa30 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f  arameter.** thro
2fa40 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
2fa50 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
2fa60 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
2fa70 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
2fa80 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2fa90 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
2faa0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
2fab0 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79   then as many by
2fac0 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
2fad0 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74  ers) of the text
2fae0 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
2faf0 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
2fb00 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73  ter are taken as
2fb10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2fb20 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63  -defined.** func
2fb30 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  tion result..** 
2fb40 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
2fb50 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
2fb60 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
2fb70 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
2fb80 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2fb90 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e  _blob is a non-N
2fba0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
2fbb0 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74  n SQLite calls t
2fbc0 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  hat.** function 
2fbd0 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  as the destructo
2fbe0 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72  r on the text or
2fbf0 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65   BLOB result whe
2fc00 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69  n it has.** fini
2fc10 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
2fc20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68  result..** If th
2fc30 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2fc40 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
2fc50 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2fc60 72 66 61 63 65 73 20 6f 72 0a 2a 2a 20 73 71 6c  rfaces or.** sql
2fc70 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2fc80 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
2fc90 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
2fca0 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c  STATIC, then SQL
2fcb0 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74  ite.** assumes t
2fcc0 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20  hat the text or 
2fcd0 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69  BLOB result is i
2fce0 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65  n constant space
2fcf0 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a   and does not.**
2fd00 20 63 6f 70 79 20 74 68 65 20 69 74 20 6f 72 20   copy the it or 
2fd10 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f  call a destructo
2fd20 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  r when it has fi
2fd30 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
2fd40 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20  t result..** If 
2fd50 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
2fd60 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
2fd70 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2fd80 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
2fd90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2fda0 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
2fdb0 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
2fdc0 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74  E_TRANSIENT.** t
2fdd0 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  hen SQLite makes
2fde0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72   a copy of the r
2fdf0 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65  esult into space
2fe00 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a   obtained from.*
2fe10 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
2fe20 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65  malloc()] before
2fe30 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
2fe40 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2fe50 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
2fe60 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
2fe70 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
2fe80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2fe90 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2fea0 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a  o be a copy the.
2feb0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
2fec0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2fed0 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20  bject specified 
2fee0 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
2fef0 65 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71  eter.  The.** sq
2ff00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2ff10 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  ue() interface m
2ff20 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
2ff30 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2ff40 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68  e].** so that th
2ff50 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2ff60 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  ] specified in t
2ff70 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
2ff80 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65   change or.** be
2ff90 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74   deallocated aft
2ffa0 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  er sqlite3_resul
2ffb0 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e  t_value() return
2ffc0 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  s without harm..
2ffd0 2a 2a 20 41 20 5b 70 72 6f 74 65 63 74 65 64 20  ** A [protected 
2ffe0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2fff0 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73  bject may always
30000 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61   be used where a
30010 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
30020 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
30030 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69   object is requi
30040 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a  red, so either.*
30050 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74  * kind of [sqlit
30060 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
30070 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74   can be used wit
30080 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  h this interface
30090 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65  ..**.** If these
300a0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
300b0 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e  lled from within
300c0 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74   the different t
300d0 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68  hread.** than th
300e0 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67  e one containing
300f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
30100 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
30110 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a  n that received.
30120 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
30130 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72  context] pointer
30140 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
30150 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
30160 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
30170 2a 0a 2a 2a 20 7b 46 31 36 34 30 33 7d 20 54 68  *.** {F16403} Th
30180 65 20 64 65 66 61 75 6c 74 20 72 65 74 75 72 6e  e default return
30190 20 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 79 20   value from any 
301a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
301b0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  NULL..**.** {F16
301c0 34 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  406} The [sqlite
301d0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c  3_result_blob(C,
301e0 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  V,N,D)] interfac
301f0 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
30200 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
30210 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
30220 6f 6e 20 43 20 74 6f 20 62 65 20 61 20 42 4c 4f  on C to be a BLO
30230 42 20 74 68 61 74 20 69 73 20 4e 20 62 79 74 65  B that is N byte
30240 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  s.**          in
30250 20 6c 65 6e 67 74 68 20 61 6e 64 20 77 69 74 68   length and with
30260 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 64   content pointed
30270 20 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a 2a 20   to by V..**.** 
30280 7b 46 31 36 34 30 39 7d 20 54 68 65 20 5b 73 71  {F16409} The [sq
30290 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
302a0 62 6c 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66  ble(C,V)] interf
302b0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
302c0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
302d0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
302e0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
302f0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
30300 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  value V..**.** {
30310 46 31 36 34 31 32 7d 20 54 68 65 20 5b 73 71 6c  F16412} The [sql
30320 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
30330 72 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66  r(C,V,N)] interf
30340 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20  ace changes the 
30350 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
30360 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63     value of func
30370 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20  tion C to be an 
30380 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65  exception with e
30390 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20  rror code.**    
303a0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52        [SQLITE_ER
303b0 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 2d 38  ROR] and a UTF-8
303c0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 63   error message c
303d0 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20  opied from V up 
303e0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
303f0 20 20 20 66 69 72 73 74 20 7a 65 72 6f 20 62 79     first zero by
30400 74 65 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79  te or until N by
30410 74 65 73 20 61 72 65 20 72 65 61 64 20 69 66 20  tes are read if 
30420 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a  N is positive..*
30430 2a 0a 2a 2a 20 7b 46 31 36 34 31 35 7d 20 54 68  *.** {F16415} Th
30440 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
30450 74 5f 65 72 72 6f 72 31 36 28 43 2c 56 2c 4e 29  t_error16(C,V,N)
30460 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
30470 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
30480 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
30490 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
304a0 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f  o be an exceptio
304b0 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64  n with error cod
304c0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  e.**          [S
304d0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64  QLITE_ERROR] and
304e0 20 61 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65   a UTF-16 native
304f0 20 62 79 74 65 20 6f 72 64 65 72 20 65 72 72 6f   byte order erro
30500 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20  r message.**    
30510 20 20 20 20 20 20 63 6f 70 69 65 64 20 66 72 6f        copied fro
30520 6d 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69  m V up to the fi
30530 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
30540 74 6f 72 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62  tor or until N b
30550 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ytes.**         
30560 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 20 69   are read if N i
30570 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a  s positive..**.*
30580 2a 20 7b 46 31 36 34 31 38 7d 20 54 68 65 20 5b  * {F16418} The [
30590 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
305a0 72 72 6f 72 5f 74 6f 6f 62 69 67 28 43 29 5d 20  rror_toobig(C)] 
305b0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
305c0 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20  s the return.** 
305d0 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
305e0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43  f the function C
305f0 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74   to be an except
30600 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63  ion with error c
30610 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ode.**          
30620 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20  [SQLITE_TOOBIG] 
30630 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61  and an appropria
30640 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  te error message
30650 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 31 7d  ..**.** {F16421}
30660 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
30670 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
30680 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (C)] interface c
30690 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72  hanges the retur
306a0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  n.**          va
306b0 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74  lue of the funct
306c0 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65  ion C to be an e
306d0 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72  xception with er
306e0 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20  ror code.**     
306f0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d       [SQLITE_NOM
30700 45 4d 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f  EM] and an appro
30710 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73  priate error mes
30720 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  sage..**.** {F16
30730 34 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  424} The [sqlite
30740 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
30750 6f 64 65 28 43 2c 45 29 5d 20 69 6e 74 65 72 66  ode(C,E)] interf
30760 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20  ace changes the 
30770 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
30780 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20     value of the 
30790 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
307a0 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69   an exception wi
307b0 74 68 20 65 72 72 6f 72 20 63 6f 64 65 20 45 2e  th error code E.
307c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 54 68 65  .**          The
307d0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
307e0 65 78 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  ext is unchanged
307f0 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 32 37 7d  ..**.** {F16427}
30800 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
30810 73 75 6c 74 5f 69 6e 74 28 43 2c 56 29 5d 20 69  sult_int(C,V)] i
30820 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
30830 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
30840 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
30850 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
30860 65 20 74 68 65 20 33 32 2d 62 69 74 20 69 6e 74  e the 32-bit int
30870 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a  eger value V..**
30880 0a 2a 2a 20 7b 46 31 36 34 33 30 7d 20 54 68 65  .** {F16430} The
30890 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
308a0 5f 69 6e 74 36 34 28 43 2c 56 29 5d 20 69 6e 74  _int64(C,V)] int
308b0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
308c0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
308d0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
308e0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
308f0 74 68 65 20 36 34 2d 62 69 74 20 69 6e 74 65 67  the 64-bit integ
30900 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a  er value V..**.*
30910 2a 20 7b 46 31 36 34 33 33 7d 20 54 68 65 20 5b  * {F16433} The [
30920 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
30930 75 6c 6c 28 43 29 5d 20 69 6e 74 65 72 66 61 63  ull(C)] interfac
30940 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
30950 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
30960 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
30970 6f 6e 20 43 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  on C to be NULL.
30980 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 33 36 7d 20  .**.** {F16436} 
30990 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
309a0 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44  ult_text(C,V,N,D
309b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
309c0 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
309d0 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
309e0 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
309f0 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d 38 20  to be the UTF-8 
30a00 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  string.**       
30a10 20 20 20 56 20 75 70 20 74 6f 20 74 68 65 20 66     V up to the f
30a20 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69  irst zero if N i
30a30 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20  s negative.**   
30a40 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69         or the fi
30a50 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56  rst N bytes of V
30a60 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67   if N is non-neg
30a70 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ative..**.** {F1
30a80 36 34 33 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  6439} The [sqlit
30a90 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
30aa0 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72  (C,V,N,D)] inter
30ab0 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
30ac0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
30ad0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
30ae0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
30af0 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  e UTF-16 native 
30b00 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
30b10 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20         string V 
30b20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
30b30 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67  zero if N is neg
30b40 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  ative.**        
30b50 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e    or the first N
30b60 20 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e   bytes of V if N
30b70 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
30b80 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34 32 7d  ..**.** {F16442}
30b90 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
30ba0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c  sult_text16be(C,
30bb0 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  V,N,D)] interfac
30bc0 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
30bd0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
30be0 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
30bf0 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55  on C to be the U
30c00 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e  TF-16 big-endian
30c10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
30c20 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65 20  ing V up to the 
30c30 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20  first zero if N 
30c40 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20  is negative.**  
30c50 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66          or the f
30c60 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 72 20  irst N bytes or 
30c70 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65  V if N is non-ne
30c80 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46  gative..**.** {F
30c90 31 36 34 34 35 7d 20 54 68 65 20 5b 73 71 6c 69  16445} The [sqli
30ca0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
30cb0 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e  6le(C,V,N,D)] in
30cc0 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
30cd0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
30ce0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
30cf0 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
30d00 20 74 68 65 20 55 54 46 2d 31 36 20 6c 69 74 74   the UTF-16 litt
30d10 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20  le-endian.**    
30d20 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20 75        string V u
30d30 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
30d40 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61  ero if N is nega
30d50 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  tive.**         
30d60 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20   or the first N 
30d70 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20  bytes of V if N 
30d80 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e  is non-negative.
30d90 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 34 34 38 7d 20  .**.** {F16448} 
30da0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
30db0 75 6c 74 5f 76 61 6c 75 65 28 43 2c 56 29 5d 20  ult_value(C,V)] 
30dc0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
30dd0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
30de0 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
30df0 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
30e00 62 65 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  be the [unprotec
30e10 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
30e20 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  e].**          o
30e30 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  bject V..**.** {
30e40 46 31 36 34 35 31 7d 20 54 68 65 20 5b 73 71 6c  F16451} The [sql
30e50 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
30e60 62 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74 65 72  blob(C,N)] inter
30e70 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
30e80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
30e90 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
30ea0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
30eb0 20 4e 2d 62 79 74 65 20 42 4c 4f 42 20 6f 66 20   N-byte BLOB of 
30ec0 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a  all zeros..**.**
30ed0 20 7b 46 31 36 34 35 34 7d 20 54 68 65 20 5b 73   {F16454} The [s
30ee0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
30ef0 72 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ror()] and [sqli
30f00 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
30f10 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  16()].**        
30f20 20 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b    interfaces mak
30f30 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 69  e a copy of thei
30f40 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  r error message 
30f50 73 74 72 69 6e 67 73 20 62 65 66 6f 72 65 0a 2a  strings before.*
30f60 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
30f70 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36  ning..**.** {F16
30f80 34 35 37 7d 20 49 66 20 74 68 65 20 44 20 64 65  457} If the D de
30f90 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74  structor paramet
30fa0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  er to [sqlite3_r
30fb0 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
30fc0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
30fd0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
30fe0 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d  t_text(C,V,N,D)]
30ff0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  , [sqlite3_resul
31000 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
31010 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
31020 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
31030 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
31040 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
31050 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
31060 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c  lt_text16le(C,V,
31070 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e  N,D)] is the con
31080 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54  stant [SQLITE_ST
31090 41 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ATIC].**        
310a0 20 20 74 68 65 6e 20 6e 6f 20 64 65 73 74 72 75    then no destru
310b0 63 74 6f 72 20 69 73 20 65 76 65 72 20 63 61 6c  ctor is ever cal
310c0 6c 65 64 20 6f 6e 20 74 68 65 20 70 6f 69 6e 74  led on the point
310d0 65 72 20 56 20 61 6e 64 20 53 51 4c 69 74 65 0a  er V and SQLite.
310e0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 75  **          assu
310f0 6d 65 73 20 74 68 61 74 20 56 20 69 73 20 69 6d  mes that V is im
31100 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b  mutable..**.** {
31110 46 31 36 34 36 30 7d 20 49 66 20 74 68 65 20 44  F16460} If the D
31120 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61   destructor para
31130 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
31140 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c  3_result_blob(C,
31150 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,N,D)],.**     
31160 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
31170 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c  sult_text(C,V,N,
31180 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  D)], [sqlite3_re
31190 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c  sult_text16(C,V,
311a0 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  N,D)],.**       
311b0 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
311c0 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c  lt_text16be(C,V,
311d0 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  N,D)], or.**    
311e0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
311f0 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43  esult_text16le(C
31200 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20  ,V,N,D)] is the 
31210 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20 20 20  constant.**     
31220 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 52 41       [SQLITE_TRA
31230 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 74 68 65  NSIENT] then the
31240 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65   interfaces make
31250 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
31260 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74  **          cont
31270 65 6e 74 20 6f 66 20 56 20 61 6e 64 20 72 65 74  ent of V and ret
31280 61 69 6e 73 20 74 68 65 20 63 6f 70 79 2e 0a 2a  ains the copy..*
31290 2a 0a 2a 2a 20 7b 46 31 36 34 36 33 7d 20 49 66  *.** {F16463} If
312a0 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f   the D destructo
312b0 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  r parameter to [
312c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
312d0 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a  lob(C,V,N,D)],.*
312e0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
312f0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
31300 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69  C,V,N,D)], [sqli
31310 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
31320 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  6(C,V,N,D)],.** 
31330 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
31340 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
31350 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a  e(C,V,N,D)], or.
31360 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
31370 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
31380 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  16le(C,V,N,D)] i
31390 73 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f 74 68  s some value oth
313a0 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  er than.**      
313b0 20 20 20 20 74 68 65 20 63 6f 6e 73 74 61 6e 74      the constant
313c0 73 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  s [SQLITE_STATIC
313d0 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 54 52  ] and [SQLITE_TR
313e0 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 0a 2a 2a  ANSIENT] then.**
313f0 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65            SQLite
31400 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
31410 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69   destructor D wi
31420 74 68 20 56 20 61 73 20 69 74 73 20 6f 6e 6c 79  th V as its only
31430 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20   argument.**    
31440 20 20 20 20 20 20 77 68 65 6e 20 69 74 20 68 61        when it ha
31450 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
31460 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a 2f 0a  the V value..*/.
31470 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
31480 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ult_blob(sqlite3
31490 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
314a0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
314b0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
314c0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
314d0 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
314e0 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
314f0 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  e);.void sqlite3
31500 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
31510 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
31520 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
31530 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
31540 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
31550 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
31560 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
31570 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
31580 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
31590 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e  obig(sqlite3_con
315a0 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
315b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
315c0 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f  r_nomem(sqlite3_
315d0 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
315e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
315f0 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
31600 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
31610 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
31620 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
31630 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
31640 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
31650 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
31660 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
31670 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f  lite3_int64);.vo
31680 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
31690 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
316a0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
316b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
316c0 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
316d0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
316e0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
316f0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
31700 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
31710 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
31720 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
31730 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
31740 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
31750 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
31760 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
31770 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
31780 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
31790 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
317a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
317b0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
317c0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
317d0 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
317e0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
317f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
31800 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
31810 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
31820 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  lue*);.void sqli
31830 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
31840 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
31850 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f  ext*, int n);../
31860 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
31870 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74  efine New Collat
31880 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20 7b 46  ing Sequences {F
31890 31 36 36 30 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  16600}.**.** The
318a0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
318b0 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77   used to add new
318c0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
318d0 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b  nces to the.** [
318e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
318f0 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61  ion] specified a
31900 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
31910 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
31920 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20  name of the new 
31930 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
31940 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20  ce is specified 
31950 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  as a UTF-8 strin
31960 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
31970 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
31980 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
31990 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
319a0 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
319b0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72  TF-16 string for
319c0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
319d0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49  collation16(). I
319e0 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74  n all cases.** t
319f0 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65  he name is passe
31a00 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
31a10 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
31a20 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  t..**.** The thi
31a30 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20  rd argument may 
31a40 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  be one of the co
31a50 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f  nstants [SQLITE_
31a60 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  UTF8],.** [SQLIT
31a70 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53  E_UTF16LE] or [S
31a80 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20  QLITE_UTF16BE], 
31a90 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
31aa0 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65  the user-supplie
31ab0 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70  d.** routine exp
31ac0 65 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 65  ects to be passe
31ad0 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  d pointers to st
31ae0 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73  rings encoded us
31af0 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54  ing UTF-8,.** UT
31b00 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69  F-16 little-endi
31b10 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
31b20 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g-endian, respec
31b30 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74  tively. The.** t
31b40 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69  hird argument mi
31b50 67 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c  ght also be [SQL
31b60 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
31b70 44 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  D] to indicate t
31b80 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69  hat.** the routi
31b90 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74  ne expects point
31ba0 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f  ers to 16-bit wo
31bb0 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e  rd aligned strin
31bc0 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20  gs.** of UTF-16 
31bd0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
31be0 74 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 20  te order of the 
31bf0 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a  host computer..*
31c00 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  *.** A pointer t
31c10 6f 20 74 68 65 20 75 73 65 72 20 73 75 70 70 6c  o the user suppl
31c20 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  ied routine must
31c30 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
31c40 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d  e fifth.** argum
31c50 65 6e 74 2e 20 20 49 66 20 69 74 20 69 73 20 4e  ent.  If it is N
31c60 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65  ULL, this is the
31c70 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e   same as deletin
31c80 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a  g the collation.
31c90 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20  ** sequence (so 
31ca0 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e  that SQLite cann
31cb0 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f  ot call it anymo
31cc0 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d  re)..** Each tim
31cd0 65 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  e the applicatio
31ce0 6e 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74  n supplied funct
31cf0 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ion is invoked, 
31d00 69 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20  it is passed.** 
31d10 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61 72  as its first par
31d20 61 6d 65 74 65 72 20 61 20 63 6f 70 79 20 6f 66  ameter a copy of
31d30 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65   the void* passe
31d40 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
31d50 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
31d60 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
31d70 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  llation() or sql
31d80 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
31d90 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a  ation16()..**.**
31da0 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61   The remaining a
31db0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
31dc0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70  application-supp
31dd0 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65  lied routine are
31de0 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a   two strings,.**
31df0 20 65 61 63 68 20 72 65 70 72 65 73 65 6e 74 65   each represente
31e00 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c 20  d by a (length, 
31e10 64 61 74 61 29 20 70 61 69 72 20 61 6e 64 20 65  data) pair and e
31e20 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e  ncoded in the en
31e30 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77  coding.** that w
31e40 61 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65  as passed as the
31e50 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
31e60 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  when the collati
31e70 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a  on sequence was.
31e80 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20 7b  ** registered. {
31e90 45 4e 44 7d 20 20 54 68 65 20 61 70 70 6c 69 63  END}  The applic
31ea0 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f  ation defined co
31eb0 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20  llation routine 
31ec0 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
31ed0 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20   negative, zero 
31ee0 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 20 74  or positive if t
31ef0 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20  he first string 
31f00 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a  is less than,.**
31f10 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72   equal to, or gr
31f20 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73  eater than the s
31f30 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e  econd string. i.
31f40 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54  e. (STRING1 - ST
31f50 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  RING2)..**.** Th
31f60 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
31f70 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
31f80 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
31f90 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
31fa0 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  ion().** except 
31fb0 74 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e  that it takes an
31fc0 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20   extra argument 
31fd0 77 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72  which is a destr
31fe0 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65  uctor for.** the
31ff0 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65   collation.  The
32000 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
32010 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63  alled when the c
32020 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64  ollation is.** d
32030 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20  estroyed and is 
32040 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66  passed a copy of
32050 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
32060 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e  meter void* poin
32070 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ter.** of the sq
32080 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
32090 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20  lation_v2()..** 
320a0 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64  Collations are d
320b0 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20 74 68  estroyed when th
320c0 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65  ey are overridde
320d0 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73  n by later calls
320e0 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61   to the.** colla
320f0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75  tion creation fu
32100 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20  nctions or when 
32110 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
32120 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f  nnection] is clo
32130 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  sed.** using [sq
32140 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
32150 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
32160 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 33 7d  :.**.** {F16603}
32170 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
32180 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  ll to the.**    
32190 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
321a0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
321b0 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
321c0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20   interface.**   
321d0 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 73         registers
321e0 20 66 75 6e 63 74 69 6f 6e 20 46 20 61 73 20 74   function F as t
321f0 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75  he comparison fu
32200 6e 63 74 69 6f 6e 20 75 73 65 64 20 74 6f 0a 2a  nction used to.*
32210 2a 20 20 20 20 20 20 20 20 20 20 69 6d 70 6c 65  *          imple
32220 6d 65 6e 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 58  ment collation X
32230 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
32240 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20  e connection] B 
32250 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
32260 64 61 74 61 62 61 73 65 73 20 68 61 76 69 6e 67  databases having
32270 20 65 6e 63 6f 64 69 6e 67 20 45 2e 0a 2a 2a 0a   encoding E..**.
32280 2a 2a 20 7b 46 31 36 36 30 34 7d 20 53 51 4c 69  ** {F16604} SQLi
32290 74 65 20 75 6e 64 65 72 73 74 61 6e 64 73 20 74  te understands t
322a0 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20 74  he X parameter t
322b0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
322c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
322d0 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
322e0 2c 50 2c 46 2c 44 29 5d 20 61 73 20 61 20 7a 65  ,P,F,D)] as a ze
322f0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
32300 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20            UTF-8 
32310 73 74 72 69 6e 67 20 69 6e 20 77 68 69 63 68 20  string in which 
32320 63 61 73 65 20 69 73 20 69 67 6e 6f 72 65 64 20  case is ignored 
32330 66 6f 72 20 41 53 43 49 49 20 63 68 61 72 61 63  for ASCII charac
32340 74 65 72 73 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ters and.**     
32350 20 20 20 20 20 69 73 20 73 69 67 6e 69 66 69 63       is signific
32360 61 6e 74 20 66 6f 72 20 6e 6f 6e 2d 41 53 43 49  ant for non-ASCI
32370 49 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  I characters..**
32380 0a 2a 2a 20 7b 46 31 36 36 30 36 7d 20 53 75 63  .** {F16606} Suc
32390 63 65 73 73 69 76 65 20 63 61 6c 6c 73 20 74 6f  cessive calls to
323a0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
323b0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
323c0 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20  X,E,P,F,D)].**  
323d0 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68 65          with the
323e0 20 73 61 6d 65 20 76 61 6c 75 65 73 20 66 6f 72   same values for
323f0 20 42 2c 20 58 2c 20 61 6e 64 20 45 2c 20 6f 76   B, X, and E, ov
32400 65 72 72 69 64 65 20 70 72 69 6f 72 20 76 61 6c  erride prior val
32410 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ues.**          
32420 6f 66 20 50 2c 20 46 2c 20 61 6e 64 20 44 2e 0a  of P, F, and D..
32430 2a 2a 0a 2a 2a 20 7b 46 31 36 36 30 39 7d 20 49  **.** {F16609} I
32440 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
32450 20 44 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63   D in [sqlite3_c
32460 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
32470 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
32480 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
32490 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 69 74  not NULL then it
324a0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
324b0 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 20  argument P when 
324c0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
324d0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
324e0 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 62 79  on is dropped by
324f0 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b   SQLite..**.** {
32500 46 31 36 36 31 32 7d 20 41 20 63 6f 6c 6c 61 74  F16612} A collat
32510 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
32520 64 72 6f 70 70 65 64 20 77 68 65 6e 20 69 74 20  dropped when it 
32530 69 73 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a  is overloaded..*
32540 2a 0a 2a 2a 20 7b 46 31 36 36 31 35 7d 20 41 20  *.** {F16615} 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 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
32580 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20  connection.**   
32590 20 20 20 20 20 20 20 69 73 20 63 6c 6f 73 65 64         is closed
325a0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
325b0 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  close()]..**.** 
325c0 7b 46 31 36 36 31 38 7d 20 54 68 65 20 70 6f 69  {F16618} The poi
325d0 6e 74 65 72 20 50 20 69 6e 20 5b 73 71 6c 69 74  nter P in [sqlit
325e0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
325f0 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46  ion_v2(B,X,E,P,F
32600 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,D)].**         
32610 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
32620 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
32630 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
32640 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20   comparison.**  
32650 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e          function
32660 20 46 20 66 6f 72 20 61 6c 6c 20 73 75 62 73 65   F for all subse
32670 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
32680 73 20 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b 46  s of F..**.** {F
32690 31 36 36 32 31 7d 20 41 20 63 61 6c 6c 20 74 6f  16621} A call to
326a0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
326b0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45  _collation(B,X,E
326c0 2c 50 2c 46 29 5d 20 69 73 20 65 78 61 63 74 6c  ,P,F)] is exactl
326d0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  y.**          th
326e0 65 20 73 61 6d 65 20 61 73 20 61 20 63 61 6c 6c  e same as a call
326f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
32700 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
32710 28 29 5d 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  ()] with.**     
32720 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 70 61       the same pa
32730 72 61 6d 65 74 65 72 73 20 61 6e 64 20 61 20 4e  rameters and a N
32740 55 4c 4c 20 64 65 73 74 72 75 63 74 6f 72 2e 0a  ULL destructor..
32750 2a 2a 0a 2a 2a 20 7b 46 31 36 36 32 34 7d 20 46  **.** {F16624} F
32760 6f 6c 6c 6f 77 69 6e 67 20 61 20 5b 73 71 6c 69  ollowing a [sqli
32770 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
32780 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c  tion_v2(B,X,E,P,
32790 46 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  F,D)],.**       
327a0 20 20 20 53 51 4c 69 74 65 20 75 73 65 73 20 74     SQLite uses t
327b0 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75  he comparison fu
327c0 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c  nction F for all
327d0 20 74 65 78 74 20 63 6f 6d 70 61 72 69 73 6f 6e   text comparison
327e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 70 65  .**          ope
327f0 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 5b  rations on the [
32800 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32810 69 6f 6e 5d 20 42 20 6f 6e 20 74 65 78 74 20 76  ion] B on text v
32820 61 6c 75 65 73 20 74 68 61 74 0a 2a 2a 20 20 20  alues that.**   
32830 20 20 20 20 20 20 20 75 73 65 20 74 68 65 20 63         use the c
32840 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63  ollating sequenc
32850 65 20 6e 61 6d 65 64 20 58 2e 0a 2a 2a 0a 2a 2a  e named X..**.**
32860 20 7b 46 31 36 36 32 37 7d 20 54 68 65 20 5b 73   {F16627} The [s
32870 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
32880 6c 6c 61 74 69 6f 6e 31 36 28 42 2c 58 2c 45 2c  llation16(B,X,E,
32890 50 2c 46 29 5d 20 77 6f 72 6b 73 20 74 68 65 20  P,F)] works the 
328a0 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
328b0 20 61 73 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   as [sqlite3_cre
328c0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c  ate_collation(B,
328d0 58 2c 45 2c 50 2c 46 29 5d 20 65 78 63 65 70 74  X,E,P,F)] except
328e0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20   that the.**    
328f0 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20        collation 
32900 6e 61 6d 65 20 58 20 69 73 20 75 6e 64 65 72 73  name X is unders
32910 74 6f 6f 64 20 61 73 20 55 54 46 2d 31 36 20 69  tood as UTF-16 i
32920 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
32930 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
32940 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38  instead of UTF-8
32950 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 36 33 30 7d  ..**.** {F16630}
32960 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 63   When multiple c
32970 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69  omparison functi
32980 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ons are availabl
32990 65 20 66 6f 72 20 74 68 65 20 73 61 6d 65 0a 2a  e for the same.*
329a0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61  *          colla
329b0 74 69 6e 67 20 73 65 71 75 65 6e 63 65 2c 20 53  ting sequence, S
329c0 51 4c 69 74 65 20 63 68 6f 6f 73 65 73 20 74 68  QLite chooses th
329d0 65 20 6f 6e 65 20 77 68 6f 73 65 20 74 65 78 74  e one whose text
329e0 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 20 20 20   encoding.**    
329f0 20 20 20 20 20 20 72 65 71 75 69 72 65 73 20 74        requires t
32a00 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
32a10 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72  of conversion fr
32a20 6f 6d 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a  om the default.*
32a30 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20  *          text 
32a40 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20  encoding of the 
32a50 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74  database..*/.int
32a60 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32a70 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c  collation(.  sql
32a80 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
32a90 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
32aa0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
32ab0 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
32ac0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
32ad0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
32ae0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
32af0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
32b00 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
32b10 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  v2(.  sqlite3*, 
32b20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
32b30 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
32b40 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
32b50 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
32b60 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
32b70 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
32b80 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
32b90 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
32ba0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
32bb0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
32bc0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
32bd0 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  , .  const void 
32be0 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54  *zName,.  int eT
32bf0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a  extRep, .  void*
32c00 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
32c10 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
32c20 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
32c30 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
32c40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
32c50 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43  llation Needed C
32c60 61 6c 6c 62 61 63 6b 73 20 7b 46 31 36 37 30 30  allbacks {F16700
32c70 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64  }.**.** To avoid
32c80 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73   having to regis
32c90 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f  ter all collatio
32ca0 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f  n sequences befo
32cb0 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  re a database.**
32cc0 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20   can be used, a 
32cd0 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20  single callback 
32ce0 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
32cf0 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
32d00 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
32d10 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
32d20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76  be called whenev
32d30 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
32d40 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
32d50 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65  uence is require
32d60 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
32d70 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69  function is regi
32d80 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
32d90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
32da0 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c  on_needed() API,
32db0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70  .** then it is p
32dc0 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20  assed the names 
32dd0 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  of undefined col
32de0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
32df0 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65   as strings.** e
32e00 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e  ncoded in UTF-8.
32e10 20 7b 46 31 36 37 30 33 7d 20 49 66 20 73 71 6c   {F16703} If sql
32e20 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
32e30 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
32e40 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20  d,.** the names 
32e50 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
32e60 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
32e70 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
32e80 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  r..** A call to 
32e90 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20  either function 
32ea0 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69  replaces any exi
32eb0 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a  sting callback..
32ec0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
32ed0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
32ee0 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72  ed, the first ar
32ef0 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73  gument passed is
32f00 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
32f10 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
32f20 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  t to sqlite3_col
32f30 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
32f40 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
32f50 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
32f60 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ().  The second 
32f70 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
32f80 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
32f90 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69  ection.  The thi
32fa0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  rd argument is o
32fb0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ne of [SQLITE_UT
32fc0 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
32fd0 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  16BE],.** or [SQ
32fe0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69  LITE_UTF16LE], i
32ff0 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f  ndicating the mo
33000 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72  st desirable for
33010 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  m of the collati
33020 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66  on.** sequence f
33030 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64  unction required
33040 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
33050 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
33060 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  ame of the.** re
33070 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  quired collation
33080 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a   sequence..**.**
33090 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
330a0 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65  nction should re
330b0 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72  gister the desir
330c0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69  ed collation usi
330d0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
330e0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
330f0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
33100 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
33110 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
33120 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
33130 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  ion_v2()]..**.**
33140 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
33150 2a 2a 20 7b 46 31 36 37 30 32 7d 20 41 20 73 75  ** {F16702} A su
33160 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
33170 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
33180 69 6f 6e 5f 6e 65 65 64 65 64 28 44 2c 50 2c 46  ion_needed(D,P,F
33190 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
331a0 72 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  r [sqlite3_colla
331b0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 44 2c  tion_needed16(D,
331c0 50 2c 46 29 5d 20 63 61 75 73 65 73 0a 2a 2a 20  P,F)] causes.** 
331d0 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 64 61           the [da
331e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
331f0 6e 5d 20 44 20 74 6f 20 69 6e 76 6f 6b 65 20 63  n] D to invoke c
33200 61 6c 6c 62 61 63 6b 20 46 20 77 69 74 68 20 66  allback F with f
33210 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  irst.**         
33220 20 70 61 72 61 6d 65 74 65 72 20 50 20 77 68 65   parameter P whe
33230 6e 65 76 65 72 20 69 74 20 6e 65 65 64 73 20 61  never it needs a
33240 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63   comparison func
33250 74 69 6f 6e 20 66 6f 72 20 61 0a 2a 2a 20 20 20  tion for a.**   
33260 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67         collating
33270 20 73 65 71 75 65 6e 63 65 20 74 68 61 74 20 69   sequence that i
33280 74 20 64 6f 65 73 20 6e 6f 74 20 6b 6e 6f 77 20  t does not know 
33290 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  about..**.** {F1
332a0 36 37 30 34 7d 20 45 61 63 68 20 73 75 63 63 65  6704} Each succe
332b0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
332c0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
332d0 5f 6e 65 65 64 65 64 28 29 5d 20 6f 72 0a 2a 2a  _needed()] or.**
332e0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
332f0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
33300 64 65 64 31 36 28 29 5d 20 6f 76 65 72 72 69 64  ded16()] overrid
33310 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  es the callback 
33320 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20  registered.**   
33330 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61         on the sa
33340 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
33350 6e 65 63 74 69 6f 6e 5d 20 62 79 20 70 72 69 6f  nection] by prio
33360 72 20 63 61 6c 6c 73 20 74 6f 20 65 69 74 68 65  r calls to eithe
33370 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  r.**          in
33380 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b  terface..**.** {
33390 46 31 36 37 30 36 7d 20 54 68 65 20 6e 61 6d 65  F16706} The name
333a0 20 6f 66 20 74 68 65 20 72 65 71 75 65 73 74 65   of the requeste
333b0 64 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  d collating func
333c0 74 69 6f 6e 20 70 61 73 73 65 64 20 69 6e 20 74  tion passed in t
333d0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 34  he.**          4
333e0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
333f0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
33400 69 6e 20 55 54 46 2d 38 20 69 66 20 74 68 65 20  in UTF-8 if the 
33410 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
33420 20 20 20 20 20 77 61 73 20 72 65 67 69 73 74 65       was registe
33430 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  red using [sqlit
33440 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
33450 64 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  ded()] and.**   
33460 20 20 20 20 20 20 20 69 73 20 69 6e 20 55 54 46         is in UTF
33470 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
33480 6f 72 64 65 72 20 69 66 20 74 68 65 20 63 61 6c  order if the cal
33490 6c 62 61 63 6b 20 77 61 73 0a 2a 2a 20 20 20 20  lback was.**    
334a0 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64        registered
334b0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
334c0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
334d0 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  16()]..*/.int sq
334e0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
334f0 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65  needed(.  sqlite
33500 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20  3*, .  void*, . 
33510 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
33520 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
33530 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a  tRep,const char*
33540 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
33550 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
33560 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  d16(.  sqlite3*,
33570 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69   .  void*,.  voi
33580 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
33590 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
335a0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
335b0 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  ../*.** Specify 
335c0 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65  the key for an e
335d0 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73  ncrypted databas
335e0 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  e.  This routine
335f0 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61   should be.** ca
33600 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72  lled right after
33610 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e   sqlite3_open().
33620 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
33630 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
33640 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
33650 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
33660 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
33670 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
33680 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
33690 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
336a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
336b0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
336c0 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
336d0 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
336e0 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
336f0 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
33700 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
33710 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
33720 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
33730 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
33740 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
33750 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
33760 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
33770 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
33780 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
33790 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
337a0 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
337b0 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
337c0 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
337d0 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
337e0 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
337f0 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
33800 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
33810 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71  ite3_rekey(.  sq
33820 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
33830 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
33840 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
33850 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
33860 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
33870 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
33880 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
33890 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
338a0 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69   Suspend Executi
338b0 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54  on For A Short T
338c0 69 6d 65 20 7b 46 31 30 35 33 30 7d 0a 2a 2a 0a  ime {F10530}.**.
338d0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  ** The sqlite3_s
338e0 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20  leep() function 
338f0 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65  causes the curre
33900 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73  nt thread to sus
33910 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a  pend execution.*
33920 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61  * for at least a
33930 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
33940 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65  seconds specifie
33950 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74  d in its paramet
33960 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  er..**.** If the
33970 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
33980 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f  m does not suppo
33990 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74  rt sleep request
339a0 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73  s with.** millis
339b0 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c  econd time resol
339c0 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ution, then the 
339d0 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75  time will be rou
339e0 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68  nded up to.** th
339f0 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64  e nearest second
33a00 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  . The number of 
33a10 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
33a20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a  sleep actually.*
33a30 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d  * requested from
33a40 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
33a50 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65  ystem is returne
33a60 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  d..**.** SQLite 
33a70 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20  implements this 
33a80 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c  interface by cal
33a90 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28  ling the xSleep(
33aa0 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74  ).** method of t
33ab0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
33ac0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
33ad0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
33ae0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 33  S:.**.** {F10533
33af0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  } The [sqlite3_s
33b00 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61  leep(M)] interfa
33b10 63 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  ce invokes the x
33b20 53 6c 65 65 70 0a 2a 2a 20 20 20 20 20 20 20 20  Sleep.**        
33b30 20 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20    method of the 
33b40 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
33b50 5f 76 66 73 7c 56 46 53 5d 20 69 6e 20 6f 72 64  _vfs|VFS] in ord
33b60 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  er to.**        
33b70 20 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74    suspend execut
33b80 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
33b90 6e 74 20 74 68 72 65 61 64 20 66 6f 72 20 61 74  nt thread for at
33ba0 20 6c 65 61 73 74 0a 2a 2a 20 20 20 20 20 20 20   least.**       
33bb0 20 20 20 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64     M millisecond
33bc0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 30 35 33 36  s..**.** {F10536
33bd0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  } The [sqlite3_s
33be0 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61  leep(M)] interfa
33bf0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
33c00 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20  umber of.**     
33c10 20 20 20 20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64       millisecond
33c20 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
33c30 6c 6c 79 20 72 65 71 75 65 73 74 65 64 20 6f 66  lly requested of
33c40 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 0a 2a   the operating.*
33c50 2a 20 20 20 20 20 20 20 20 20 20 73 79 73 74 65  *          syste
33c60 6d 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20 62  m, which might b
33c70 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  e larger than th
33c80 65 20 70 61 72 61 6d 65 74 65 72 20 4d 2e 0a 2a  e parameter M..*
33c90 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c  /.int sqlite3_sl
33ca0 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  eep(int);../*.**
33cb0 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
33cc0 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f  Of The Folder Ho
33cd0 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20  lding Temporary 
33ce0 46 69 6c 65 73 20 7b 46 31 30 33 31 30 7d 0a 2a  Files {F10310}.*
33cf0 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c 6f  *.** If this glo
33d00 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
33d10 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
33d20 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
33d30 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
33d40 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e  f a folder (a.k.
33d50 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
33d60 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72  hen all temporar
33d70 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74  y files.** creat
33d80 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 69 6c  ed by SQLite wil
33d90 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74  l be placed in t
33da0 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20  hat directory.  
33db0 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
33dc0 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
33dd0 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
33de0 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65  te performs a se
33df0 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72  arch for an appr
33e00 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  opriate.** tempo
33e10 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74  rary file direct
33e20 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ory..**.** It is
33e30 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f 64   not safe to mod
33e40 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
33e50 65 20 6f 6e 63 65 20 61 20 5b 64 61 74 61 62 61  e once a [databa
33e60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
33e70 2a 20 68 61 73 20 62 65 65 6e 20 6f 70 65 6e 65  * has been opene
33e80 64 2e 20 20 49 74 20 69 73 20 69 6e 74 65 6e 64  d.  It is intend
33e90 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ed that this var
33ea0 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63  iable be set onc
33eb0 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  e.** as part of 
33ec0 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
33ed0 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72  zation and befor
33ee0 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
33ef0 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e  erface.** routin
33f00 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  es have been cal
33f10 6c 20 61 6e 64 20 72 65 6d 61 69 6e 20 75 6e 63  l and remain unc
33f20 68 61 6e 67 65 64 20 74 68 65 72 65 61 66 74 65  hanged thereafte
33f30 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  r..*/.SQLITE_EXT
33f40 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ERN char *sqlite
33f50 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
33f60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33f70 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49  F: Test To See I
33f80 66 20 54 68 65 20 44 61 74 61 62 61 73 65 20 49  f The Database I
33f90 73 20 49 6e 20 41 75 74 6f 2d 43 6f 6d 6d 69 74  s In Auto-Commit
33fa0 20 4d 6f 64 65 20 7b 46 31 32 39 33 30 7d 0a 2a   Mode {F12930}.*
33fb0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74  * KEYWORDS: {aut
33fc0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a  ocommit mode}.**
33fd0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
33fe0 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29  get_autocommit()
33ff0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
34000 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a  ns non-zero or.*
34010 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69  * zero if the gi
34020 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ven database con
34030 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73  nection is or is
34040 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d   not in autocomm
34050 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70  it mode,.** resp
34060 65 63 74 69 76 65 6c 79 2e 20 20 41 75 74 6f 63  ectively.  Autoc
34070 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e  ommit mode is on
34080 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20   by default..** 
34090 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
340a0 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61  is disabled by a
340b0 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65   [BEGIN] stateme
340c0 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69  nt..** Autocommi
340d0 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61  t mode is re-ena
340e0 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49  bled by a [COMMI
340f0 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d  T] or [ROLLBACK]
34100 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61  ..**.** If certa
34110 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f  in kinds of erro
34120 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74  rs occur on a st
34130 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
34140 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74   multi-statement
34150 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  .** transaction 
34160 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e  (errors includin
34170 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c  g [SQLITE_FULL],
34180 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c   [SQLITE_IOERR],
34190 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
341a0 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  M], [SQLITE_BUSY
341b0 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49  ], and [SQLITE_I
341c0 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20  NTERRUPT]) then 
341d0 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  the.** transacti
341e0 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c  on might be roll
341f0 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
34200 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79  cally.  The only
34210 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20   way to.** find 
34220 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69  out whether SQLi
34230 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
34240 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65   rolled back the
34250 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74   transaction aft
34260 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69  er.** an error i
34270 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75  s to use this fu
34280 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e  nction..**.** IN
34290 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
342a0 7b 46 31 32 39 33 31 7d 20 54 68 65 20 5b 73 71  {F12931} The [sq
342b0 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
342c0 6d 6d 69 74 28 44 29 5d 20 69 6e 74 65 72 66 61  mmit(D)] interfa
342d0 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ce returns non-z
342e0 65 72 6f 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ero or.**       
342f0 20 20 20 7a 65 72 6f 20 69 66 20 74 68 65 20 5b     zero if the [
34300 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34310 69 6f 6e 5d 20 44 20 69 73 20 6f 72 20 69 73 20  ion] D is or is 
34320 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69  not in autocommi
34330 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f  t.**          mo
34340 64 65 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  de, respectively
34350 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 32 7d  ..**.** {F12932}
34360 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
34370 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c   is on by defaul
34380 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 33  t..**.** {F12933
34390 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  } Autocommit mod
343a0 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
343b0 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 5b 42   a successful [B
343c0 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e  EGIN] statement.
343d0 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 33 34 7d 20  .**.** {F12934} 
343e0 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
343f0 69 73 20 65 6e 61 62 6c 65 64 20 62 79 20 61 20  is enabled by a 
34400 73 75 63 63 65 73 73 66 75 6c 20 5b 43 4f 4d 4d  successful [COMM
34410 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b  IT] or [ROLLBACK
34420 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  ].**          st
34430 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 4c  atement..**.** L
34440 49 4d 49 54 41 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  IMITATIONS:.**.*
34450 2a 20 7b 55 31 32 39 33 36 7d 20 49 66 20 61 6e  * {U12936} If an
34460 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61  other thread cha
34470 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d  nges the autocom
34480 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68  mit status of th
34490 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20  e database.**   
344a0 20 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f         connectio
344b0 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75  n while this rou
344c0 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c  tine is running,
344d0 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
344e0 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20   value.**       
344f0 20 20 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e     is undefined.
34500 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
34510 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73  get_autocommit(s
34520 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
34530 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
34540 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e  The Database Han
34550 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65  dle Of A Prepare
34560 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 46 31 33  d Statement {F13
34570 31 32 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  120}.**.** The s
34580 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
34590 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
345a0 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ns the [database
345b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
345c0 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20  dle.** to which 
345d0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
345e0 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20  ement] belongs. 
345f0 20 54 68 65 20 64 61 74 61 62 61 73 65 20 68 61   The database ha
34600 6e 64 6c 65 20 72 65 74 75 72 6e 65 64 20 62 79  ndle returned by
34610 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f 68  .** sqlite3_db_h
34620 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d  andle is the sam
34630 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  e database handl
34640 65 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66  e that was the f
34650 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
34660 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
34670 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63  _prepare_v2()] c
34680 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69  all (or its vari
34690 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75  ants) that was u
346a0 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65  sed to.** create
346b0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
346c0 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
346d0 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
346e0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 33 31  NTS:.**.** {F131
346f0 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  23} The [sqlite3
34700 5f 64 62 5f 68 61 6e 64 6c 65 28 53 29 5d 20 69  _db_handle(S)] i
34710 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
34720 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20   a pointer.**   
34730 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 5b 64         to the [d
34740 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34750 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  on] associated w
34760 69 74 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ith the.**      
34770 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
34780 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 73  atement] S..*/.s
34790 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
347a0 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
347b0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
347c0 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
347d0 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65  the next prepare
347e0 64 20 73 74 61 74 65 6d 65 6e 74 20 7b 46 31 33  d statement {F13
347f0 31 34 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  140}.**.** This 
34800 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
34810 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
34820 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65  he next [prepare
34830 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74  d statement] aft
34840 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f  er.** pStmt asso
34850 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
34860 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
34870 74 69 6f 6e 5d 20 70 44 62 2e 20 20 49 66 20 70  tion] pDb.  If p
34880 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20  Stmt is NULL.** 
34890 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66  then this interf
348a0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
348b0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72  inter to the fir
348c0 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
348d0 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61  ement.** associa
348e0 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74  ted with the dat
348f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34900 20 70 44 62 2e 20 20 49 66 20 6e 6f 20 70 72 65   pDb.  If no pre
34910 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
34920 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65  ** satisfies the
34930 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74   conditions of t
34940 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20  his routine, it 
34950 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a  returns NULL..**
34960 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
34970 2a 2a 0a 2a 2a 20 7b 46 31 33 31 34 33 7d 20 49  **.** {F13143} I
34980 66 20 44 20 69 73 20 61 20 5b 64 61 74 61 62 61  f D is a [databa
34990 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
349a0 68 61 74 20 68 6f 6c 64 73 20 6f 6e 65 20 6f 72  hat holds one or
349b0 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20   more.**        
349c0 20 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 5b 70    unfinalized [p
349d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
349e0 74 73 5d 20 61 6e 64 20 53 20 69 73 20 61 20 4e  ts] and S is a N
349f0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 0a 2a 2a 20  ULL pointer,.** 
34a00 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73           then [s
34a10 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
34a20 28 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65 20  (D, S)] routine 
34a30 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 70  shall return a p
34a40 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ointer.**       
34a50 20 20 20 74 6f 20 6f 6e 65 20 6f 66 20 74 68 65     to one of the
34a60 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
34a70 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
34a80 77 69 74 68 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46  with D..**.** {F
34a90 31 33 31 34 36 7d 20 49 66 20 44 20 69 73 20 61  13146} If D is a
34aa0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
34ab0 63 74 69 6f 6e 5d 20 74 68 61 74 20 68 6f 6c 64  ction] that hold
34ac0 73 20 6e 6f 20 75 6e 66 69 6e 61 6c 69 7a 65 64  s no unfinalized
34ad0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
34ae0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
34af0 73 5d 20 61 6e 64 20 53 20 69 73 20 61 20 4e 55  s] and S is a NU
34b00 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
34b10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
34b20 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
34b30 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 73  D, S)] routine s
34b40 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 4e 55  hall return a NU
34b50 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
34b60 2a 20 7b 46 31 33 31 34 39 7d 20 49 66 20 53 20  * {F13149} If S 
34b70 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
34b80 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 74 68 65  tatement] in the
34b90 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
34ba0 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20  ction] D.**     
34bb0 20 20 20 20 20 61 6e 64 20 53 20 69 73 20 6e 6f       and S is no
34bc0 74 20 74 68 65 20 6c 61 73 74 20 70 72 65 70 61  t the last prepa
34bd0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  red statement in
34be0 20 44 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20   D, then.**     
34bf0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65       [sqlite3_ne
34c00 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72  xt_stmt(D, S)] r
34c10 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74  outine shall ret
34c20 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  urn a pointer.**
34c30 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65            to the
34c40 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73   next prepared s
34c50 74 61 74 65 6d 65 6e 74 20 69 6e 20 44 20 61 66  tatement in D af
34c60 74 65 72 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  ter S..**.** {F1
34c70 33 31 35 32 7d 20 49 66 20 53 20 69 73 20 74 68  3152} If S is th
34c80 65 20 6c 61 73 74 20 5b 70 72 65 70 61 72 65 64  e last [prepared
34c90 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 74   statement] in t
34ca0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
34cb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34cc0 69 6f 6e 5d 20 44 20 74 68 65 6e 20 74 68 65 20  ion] D then the 
34cd0 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
34ce0 6d 74 28 44 2c 20 53 29 5d 0a 2a 2a 20 20 20 20  mt(D, S)].**    
34cf0 20 20 20 20 20 20 72 6f 75 74 69 6e 65 20 73 68        routine sh
34d00 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 4e 55 4c  all return a NUL
34d10 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71  L pointer..*/.sq
34d20 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69  lite3_stmt *sqli
34d30 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71  te3_next_stmt(sq
34d40 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69  lite3 *pDb, sqli
34d50 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
34d60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34d70 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f  F: Commit And Ro
34d80 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74  llback Notificat
34d90 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 46  ion Callbacks {F
34da0 31 32 39 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  12950}.**.** The
34db0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
34dc0 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
34dd0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
34de0 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
34df0 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
34e00 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
34e10 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74  action is commit
34e20 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c  ted..** Any call
34e30 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
34e40 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
34e50 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
34e60 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ok().** for the 
34e70 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
34e80 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
34e90 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73  ridden..** The s
34ea0 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
34eb0 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
34ec0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
34ed0 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
34ee0 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
34ef0 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
34f00 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74  action is commit
34f10 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c  ted..** Any call
34f20 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
34f30 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
34f40 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
34f50 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ok().** for the 
34f60 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
34f70 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
34f80 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70  ridden..** The p
34f90 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20  Arg argument is 
34fa0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 74  passed through t
34fb0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a  o the callback..
34fc0 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61  ** If the callba
34fd0 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68  ck on a commit h
34fe0 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  ook function ret
34ff0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a  urns non-zero,.*
35000 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69  * then the commi
35010 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69  t is converted i
35020 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a  nto a rollback..
35030 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
35040 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72   function was pr
35050 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
35060 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67  red, its.** pArg
35070 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
35080 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e  ed.  Otherwise N
35090 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
350a0 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 69  .**.** Registeri
350b0 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69  ng a NULL functi
350c0 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  on disables the 
350d0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
350e0 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
350f0 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20   of this API, a 
35100 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73  transaction is s
35110 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e  aid to have been
35120 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  .** rolled back 
35130 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22  if an explicit "
35140 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d  ROLLBACK" statem
35150 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c  ent is executed,
35160 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20   or.** an error 
35170 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61  or constraint ca
35180 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74  uses an implicit
35190 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63   rollback to occ
351a0 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62  ur..** The rollb
351b0 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ack callback is 
351c0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61  not invoked if a
351d0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a   transaction is.
351e0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
351f0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63   rolled back bec
35200 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73  ause the databas
35210 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
35220 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68 65 20 72  closed..** The r
35230 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b  ollback callback
35240 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
35250 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  if a transaction
35260 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61   is.** rolled ba
35270 63 6b 20 62 65 63 61 75 73 65 20 61 20 63 6f 6d  ck because a com
35280 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  mit callback ret
35290 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a  urned non-zero..
352a0 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65 63 6b 20  ** <todo> Check 
352b0 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a  on this </todo>.
352c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
352d0 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
352e0 65 72 66 61 63 65 73 20 61 6e 64 20 61 72 65 20  erfaces and are 
352f0 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
35300 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
35310 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  NTS:.**.** {F129
35320 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  51} The [sqlite3
35330 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46  _commit_hook(D,F
35340 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,P)] interface r
35350 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a 2a 20  egisters the.** 
35360 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
35370 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20  k function F to 
35380 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
35390 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65  argument P whene
353a0 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ver.**          
353b0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  a transaction co
353c0 6d 6d 69 74 73 20 6f 6e 20 74 68 65 20 5b 64 61  mmits on the [da
353d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
353e0 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  n] D..**.** {F12
353f0 39 35 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  952} The [sqlite
35400 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c  3_commit_hook(D,
35410 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  F,P)] interface 
35420 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61 72  returns the P ar
35430 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20  gument.**       
35440 20 20 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76     from the prev
35450 69 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 20 74  ious call with t
35460 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
35470 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
35480 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
35490 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72 73  NULL on the firs
354a0 74 20 63 61 6c 6c 20 66 6f 72 20 61 20 70 61 72  t call for a par
354b0 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
354c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a   connection D..*
354d0 2a 0a 2a 2a 20 7b 46 31 32 39 35 33 7d 20 45 61  *.** {F12953} Ea
354e0 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ch call to [sqli
354f0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
35500 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 68  )] overwrites th
35510 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  e callback.**   
35520 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
35530 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73  d by prior calls
35540 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35 34 7d  ..**.** {F12954}
35550 20 49 66 20 74 68 65 20 46 20 61 72 67 75 6d 65   If the F argume
35560 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  nt to [sqlite3_c
35570 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50  ommit_hook(D,F,P
35580 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20  )] is NULL.**   
35590 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20         then the 
355a0 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c  commit hook call
355b0 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 65 64  back is canceled
355c0 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b   and no callback
355d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
355e0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 74  invoked when a t
355f0 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69  ransaction commi
35600 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 35  ts..**.** {F1295
35610 35 7d 20 49 66 20 74 68 65 20 63 6f 6d 6d 69 74  5} If the commit
35620 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
35630 73 20 6e 6f 6e 2d 7a 65 72 6f 20 74 68 65 6e 20  s non-zero then 
35640 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 0a 2a 2a  the commit is.**
35650 20 20 20 20 20 20 20 20 20 20 63 6f 6e 76 65 72            conver
35660 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62  ted into a rollb
35670 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39  ack..**.** {F129
35680 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  61} The [sqlite3
35690 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
356a0 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
356b0 20 72 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a   registers the.*
356c0 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
356d0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74  ack function F t
356e0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  o be invoked wit
356f0 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65  h argument P whe
35700 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  never.**        
35710 20 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20    a transaction 
35720 72 6f 6c 6c 73 20 62 61 63 6b 20 6f 6e 20 74 68  rolls back on th
35730 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
35740 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
35750 20 7b 46 31 32 39 36 32 7d 20 54 68 65 20 5b 73   {F12962} The [s
35760 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
35770 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
35780 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
35790 68 65 20 50 0a 2a 2a 20 20 20 20 20 20 20 20 20  he P.**         
357a0 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74   argument from t
357b0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
357c0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 0a 2a   with the same.*
357d0 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
357e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
357f0 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74   D, or NULL on t
35800 68 65 20 66 69 72 73 74 20 63 61 6c 6c 0a 2a 2a  he first call.**
35810 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 61 20            for a 
35820 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
35830 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
35840 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 36 33 7d  ..**.** {F12963}
35850 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73   Each call to [s
35860 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
35870 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69 74  hook()] overwrit
35880 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
35890 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
358a0 73 74 65 72 65 64 20 62 79 20 70 72 69 6f 72 20  stered by prior 
358b0 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31  calls..**.** {F1
358c0 32 39 36 34 7d 20 49 66 20 74 68 65 20 46 20 61  2964} If the F a
358d0 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
358e0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
358f0 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55 4c  k(D,F,P)] is NUL
35900 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  L.**          th
35910 65 6e 20 74 68 65 20 72 6f 6c 6c 62 61 63 6b 20  en the rollback 
35920 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  hook callback is
35930 20 63 61 6e 63 65 6c 65 64 20 61 6e 64 20 6e 6f   canceled and no
35940 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
35950 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64        is invoked
35960 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61 63 74   when a transact
35970 69 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 2e 0a  ion rolls back..
35980 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
35990 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c  _commit_hook(sql
359a0 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
359b0 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f  id*), void*);.vo
359c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  id *sqlite3_roll
359d0 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  back_hook(sqlite
359e0 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  3*, void(*)(void
359f0 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a   *), void*);../*
35a00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
35a10 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69  ta Change Notifi
35a20 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
35a30 20 7b 46 31 32 39 37 30 7d 0a 2a 2a 0a 2a 2a 20   {F12970}.**.** 
35a40 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61  The sqlite3_upda
35a50 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  te_hook() interf
35a60 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
35a70 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
35a80 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64  n.** with the [d
35a90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35aa0 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62  on] identified b
35ab0 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
35ac0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  ment.** to be in
35ad0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
35ae0 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
35af0 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
35b00 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c  eted..** Any cal
35b10 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
35b20 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
35b30 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
35b40 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
35b50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35b60 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
35b70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
35b80 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
35b90 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
35ba0 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b  unction to invok
35bb0 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20  e when a.** row 
35bc0 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
35bd0 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
35be0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
35bf0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61  gument to the ca
35c00 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
35c10 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72   of the third ar
35c20 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
35c30 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
35c40 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ()..** The secon
35c50 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d  d callback argum
35c60 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
35c70 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b  QLITE_INSERT], [
35c80 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a  SQLITE_DELETE],.
35c90 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50  ** or [SQLITE_UP
35ca0 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67  DATE], depending
35cb0 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f   on the operatio
35cc0 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68  n that caused th
35cd0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f  e callback.** to
35ce0 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20   be invoked..** 
35cf0 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
35d00 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74  urth arguments t
35d10 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63  o the callback c
35d20 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20  ontain pointers 
35d30 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
35d40 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d  se and table nam
35d50 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
35d60 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a   affected row..*
35d70 2a 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c  * The final call
35d80 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  back parameter i
35d90 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74  s the rowid of t
35da0 68 65 20 72 6f 77 2e 20 49 6e 20 74 68 65 20 63  he row. In the c
35db0 61 73 65 20 6f 66 0a 2a 2a 20 61 6e 20 75 70 64  ase of.** an upd
35dc0 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 65  ate, this is the
35dd0 20 72 6f 77 69 64 20 61 66 74 65 72 20 74 68 65   rowid after the
35de0 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c   update takes pl
35df0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75  ace..**.** The u
35e00 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f  pdate hook is no
35e10 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69  t invoked when i
35e20 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74  nternal system t
35e30 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64  ables are.** mod
35e40 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69  ified (i.e. sqli
35e50 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71  te_master and sq
35e60 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a  lite_sequence)..
35e70 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
35e80 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72   function was pr
35e90 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
35ea0 72 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 61  red, its pArg va
35eb0 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  lue.** is return
35ec0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e  ed.  Otherwise N
35ed0 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
35ee0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
35ef0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37 31  S:.**.** {F12971
35f00 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75  } The [sqlite3_u
35f10 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50  pdate_hook(D,F,P
35f20 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  )] interface cau
35f30 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ses the callback
35f40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e  .**          fun
35f50 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e  ction F to be in
35f60 76 6f 6b 65 64 20 77 69 74 68 20 66 69 72 73 74  voked with first
35f70 20 70 61 72 61 6d 65 74 65 72 20 50 20 77 68 65   parameter P whe
35f80 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  never.**        
35f90 20 20 61 20 74 61 62 6c 65 20 72 6f 77 20 69 73    a table row is
35fa0 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72   modified, inser
35fb0 74 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20  ted, or deleted 
35fc0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  on.**          t
35fd0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
35fe0 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
35ff0 2a 20 7b 46 31 32 39 37 33 7d 20 54 68 65 20 5b  * {F12973} The [
36000 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
36010 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65  ook(D,F,P)] inte
36020 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
36030 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20  e value.**      
36040 20 20 20 20 6f 66 20 50 20 66 6f 72 20 74 68 65      of P for the
36050 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f   previous call o
36060 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
36070 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
36080 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   D,.**          
36090 6f 72 20 4e 55 4c 4c 20 66 6f 72 20 74 68 65 20  or NULL for the 
360a0 66 69 72 73 74 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  first call..**.*
360b0 2a 20 7b 46 31 32 39 37 35 7d 20 49 66 20 74 68  * {F12975} If th
360c0 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 63 61  e update hook ca
360d0 6c 6c 62 61 63 6b 20 46 20 69 6e 20 5b 73 71 6c  llback F in [sql
360e0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
360f0 28 44 2c 46 2c 50 29 5d 0a 2a 2a 20 20 20 20 20  (D,F,P)].**     
36100 20 20 20 20 20 69 73 20 4e 55 4c 4c 20 74 68 65       is NULL the
36110 6e 20 74 68 65 20 6e 6f 20 75 70 64 61 74 65 20  n the no update 
36120 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6d 61  callbacks are ma
36130 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 37  de..**.** {F1297
36140 37 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  7} Each call to 
36150 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
36160 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 6f 76 65  hook(D,F,P)] ove
36170 72 72 69 64 65 73 20 70 72 69 6f 72 20 63 61 6c  rrides prior cal
36180 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ls.**          t
36190 6f 20 74 68 65 20 73 61 6d 65 20 69 6e 74 65 72  o the same inter
361a0 66 61 63 65 20 6f 6e 20 74 68 65 20 73 61 6d 65  face on the same
361b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
361c0 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
361d0 7b 46 31 32 39 37 39 7d 20 54 68 65 20 75 70 64  {F12979} The upd
361e0 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63  ate hook callbac
361f0 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
36200 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73   when internal s
36210 79 73 74 65 6d 0a 2a 2a 20 20 20 20 20 20 20 20  ystem.**        
36220 20 20 74 61 62 6c 65 73 20 73 75 63 68 20 61 73    tables such as
36230 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61   sqlite_master a
36240 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e  nd sqlite_sequen
36250 63 65 20 61 72 65 20 6d 6f 64 69 66 69 65 64 2e  ce are modified.
36260 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 39 38 31 7d 20  .**.** {F12981} 
36270 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
36280 65 74 65 72 20 74 6f 20 74 68 65 20 75 70 64 61  eter to the upda
36290 74 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20  te callback.**  
362a0 20 20 20 20 20 20 20 20 69 73 20 6f 6e 65 20 6f          is one o
362b0 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  f [SQLITE_INSERT
362c0 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  ], [SQLITE_DELET
362d0 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50  E] or [SQLITE_UP
362e0 44 41 54 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  DATE],.**       
362f0 20 20 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20     depending on 
36300 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  the operation th
36310 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61  at caused the ca
36320 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 69 6e 76  llback to be inv
36330 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32  oked..**.** {F12
36340 39 38 33 7d 20 54 68 65 20 74 68 69 72 64 20 61  983} The third a
36350 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  nd fourth argume
36360 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  nts to the callb
36370 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e  ack contain poin
36380 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ters.**         
36390 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
363a0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
363b0 73 20 77 68 69 63 68 20 61 72 65 20 74 68 65 20  s which are the 
363c0 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
363d0 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73           databas
363e0 65 20 61 6e 64 20 74 61 62 6c 65 20 74 68 61 74  e and table that
363f0 20 69 73 20 62 65 69 6e 67 20 75 70 64 61 74 65   is being update
36400 64 2e 0a 0a 2a 2a 20 7b 46 31 32 39 38 35 7d 20  d...** {F12985} 
36410 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61  The final callba
36420 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
36430 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65  the rowid of the
36440 20 72 6f 77 20 61 66 74 65 72 0a 2a 2a 20 20 20   row after.**   
36450 20 20 20 20 20 20 20 74 68 65 20 63 68 61 6e 67         the chang
36460 65 20 6f 63 63 75 72 73 2e 0a 2a 2f 0a 76 6f 69  e occurs..*/.voi
36470 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 74  d *sqlite3_updat
36480 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65  e_hook(.  sqlite
36490 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  3*, .  void(*)(v
364a0 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20  oid *,int ,char 
364b0 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e  const *,char con
364c0 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  st *,sqlite3_int
364d0 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a  64),.  void*.);.
364e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
364f0 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
36500 6c 65 20 53 68 61 72 65 64 20 50 61 67 65 72 20  le Shared Pager 
36510 43 61 63 68 65 20 7b 46 31 30 33 33 30 7d 0a 2a  Cache {F10330}.*
36520 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61  * KEYWORDS: {sha
36530 72 65 64 20 63 61 63 68 65 7d 20 7b 73 68 61 72  red cache} {shar
36540 65 64 20 63 61 63 68 65 20 6d 6f 64 65 7d 0a 2a  ed cache mode}.*
36550 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
36560 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  e enables or dis
36570 61 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e  ables the sharin
36580 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  g of the databas
36590 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73  e cache.** and s
365a0 63 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 63  chema data struc
365b0 74 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64  tures between [d
365c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
365d0 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  on | connections
365e0 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65  ].** to the same
365f0 20 64 61 74 61 62 61 73 65 2e 20 53 68 61 72 69   database. Shari
36600 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66  ng is enabled if
36610 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   the argument is
36620 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73   true.** and dis
36630 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67  abled if the arg
36640 75 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 0a  ument is false..
36650 2a 2a 0a 2a 2a 20 43 61 63 68 65 20 73 68 61 72  **.** Cache shar
36660 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61  ing is enabled a
36670 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20  nd disabled for 
36680 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73  an entire proces
36690 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 54 68 69 73  s. {END}.** This
366a0 20 69 73 20 61 20 63 68 61 6e 67 65 20 61 73 20   is a change as 
366b0 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
366c0 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f  n 3.5.0. In prio
366d0 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
366e0 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67  Lite,.** sharing
366f0 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20   was enabled or 
36700 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63  disabled for eac
36710 68 20 74 68 72 65 61 64 20 73 65 70 61 72 61 74  h thread separat
36720 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ely..**.** The c
36730 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64  ache sharing mod
36740 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69 6e  e set by this in
36750 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73 20  terface effects 
36760 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  all subsequent.*
36770 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  * calls to [sqli
36780 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
36790 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
367a0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f  , and [sqlite3_o
367b0 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69  pen16()]..** Exi
367c0 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 63  sting database c
367d0 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69  onnections conti
367e0 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61 72  nue use the shar
367f0 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74  ing mode.** that
36800 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20 61   was in effect a
36810 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79 20  t the time they 
36820 77 65 72 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a  were opened..**.
36830 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  ** Virtual table
36840 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65 64  s cannot be used
36850 20 77 69 74 68 20 61 20 73 68 61 72 65 64 20 63   with a shared c
36860 61 63 68 65 2e 20 20 57 68 65 6e 20 73 68 61 72  ache.  When shar
36870 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
36880 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c  nabled, the [sql
36890 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
368a0 6c 65 28 29 5d 20 41 50 49 20 75 73 65 64 20 74  le()] API used t
368b0 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76 69  o register.** vi
368c0 72 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69 6c  rtual tables wil
368d0 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
368e0 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20  an error..**.** 
368f0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
36900 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
36910 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65   if shared cache
36920 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20   was enabled or 
36930 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63  disabled.** succ
36940 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65  essfully.  An [e
36950 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
36960 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65  turned otherwise
36970 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 20 63  ..**.** Shared c
36980 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64  ache is disabled
36990 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74   by default. But
369a0 20 74 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e   this might chan
369b0 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  ge in.** future 
369c0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
369d0 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  te.  Application
369e0 73 20 74 68 61 74 20 63 61 72 65 20 61 62 6f 75  s that care abou
369f0 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
36a00 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64  e setting should
36a10 20 73 65 74 20 69 74 20 65 78 70 6c 69 63 69 74   set it explicit
36a20 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ly..**.** INVARI
36a30 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 46 31 30  ANTS:.**.** {F10
36a40 33 33 31 7d 20 41 20 73 75 63 63 65 73 73 66 75  331} A successfu
36a50 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  l invocation of 
36a60 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
36a70 73 68 61 72 65 64 5f 63 61 63 68 65 28 42 29 5d  shared_cache(B)]
36a80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c  .**          wil
36a90 6c 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  l enable or disa
36aa0 62 6c 65 20 73 68 61 72 65 64 20 63 61 63 68 65  ble shared cache
36ab0 20 6d 6f 64 65 20 66 6f 72 20 61 6e 79 20 73 75   mode for any su
36ac0 62 73 65 71 75 65 6e 74 6c 79 0a 2a 2a 20 20 20  bsequently.**   
36ad0 20 20 20 20 20 20 20 63 72 65 61 74 65 64 20 5b         created [
36ae0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36af0 69 6f 6e 5d 20 69 6e 20 74 68 65 20 73 61 6d 65  ion] in the same
36b00 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20   process..**.** 
36b10 7b 46 31 30 33 33 36 7d 20 57 68 65 6e 20 73 68  {F10336} When sh
36b20 61 72 65 64 20 63 61 63 68 65 20 69 73 20 65 6e  ared cache is en
36b30 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69  abled, the [sqli
36b40 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
36b50 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  e()].**         
36b60 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
36b70 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e  always return an
36b80 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 46   error..**.** {F
36b90 31 30 33 33 37 7d 20 54 68 65 20 5b 73 71 6c 69  10337} The [sqli
36ba0 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
36bb0 64 5f 63 61 63 68 65 28 42 29 5d 20 69 6e 74 65  d_cache(B)] inte
36bc0 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
36bd0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
36be0 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20  E_OK] if shared 
36bf0 63 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65  cache was enable
36c00 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 73 75  d or disabled su
36c10 63 63 65 73 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a  ccessfully..**.*
36c20 2a 20 7b 46 31 30 33 33 39 7d 20 53 68 61 72 65  * {F10339} Share
36c30 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62  d cache is disab
36c40 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
36c50 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
36c60 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
36c70 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  he(int);../*.** 
36c80 43 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70  CAPI3REF: Attemp
36c90 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d  t To Free Heap M
36ca0 65 6d 6f 72 79 20 7b 46 31 37 33 34 30 7d 0a 2a  emory {F17340}.*
36cb0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
36cc0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
36cd0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
36ce0 6d 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62  mpts to free N b
36cf0 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20  ytes.** of heap 
36d00 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f  memory by deallo
36d10 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e  cating non-essen
36d20 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  tial memory allo
36d30 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20  cations.** held 
36d40 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
36d50 6c 69 62 72 61 72 79 2e 20 7b 45 4e 44 7d 20 20  library. {END}  
36d60 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 6f 20 63  Memory used to c
36d70 61 63 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  ache database.**
36d80 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76   pages to improv
36d90 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73  e performance is
36da0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e   an example of n
36db0 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d  on-essential mem
36dc0 6f 72 79 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ory..** sqlite3_
36dd0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
36de0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
36df0 62 65 72 20 6f 66 20 62 79 74 65 73 20 61 63 74  ber of bytes act
36e00 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20  ually freed,.** 
36e10 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d  which might be m
36e20 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 68 61 6e  ore or less than
36e30 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75   the amount requ
36e40 65 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ested..**.** INV
36e50 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
36e60 46 31 37 33 34 31 7d 20 54 68 65 20 5b 73 71 6c  F17341} The [sql
36e70 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
36e80 6f 72 79 28 4e 29 5d 20 69 6e 74 65 72 66 61 63  ory(N)] interfac
36e90 65 20 61 74 74 65 6d 70 74 73 20 74 6f 0a 2a 2a  e attempts to.**
36ea0 20 20 20 20 20 20 20 20 20 20 66 72 65 65 20 4e            free N
36eb0 20 62 79 74 65 73 20 6f 66 20 68 65 61 70 20 6d   bytes of heap m
36ec0 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63  emory by dealloc
36ed0 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74  ating non-essent
36ee0 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ial.**          
36ef0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
36f00 6e 73 20 68 65 6c 64 20 62 79 20 74 68 65 20 64  ns held by the d
36f10 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e  atabase library.
36f20 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 34 32 7d 20  .**.** {F16342} 
36f30 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c  The [sqlite3_rel
36f40 65 61 73 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20  ease_memory(N)] 
36f50 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
36f60 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  er.**          o
36f70 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79  f bytes actually
36f80 20 66 72 65 65 64 2c 20 77 68 69 63 68 20 6d 69   freed, which mi
36f90 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c  ght be more or l
36fa0 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ess.**          
36fb0 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  than the amount 
36fc0 72 65 71 75 65 73 74 65 64 2e 0a 2a 2f 0a 69 6e  requested..*/.in
36fd0 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  t sqlite3_releas
36fe0 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a  e_memory(int);..
36ff0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37000 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f  Impose A Limit O
37010 6e 20 48 65 61 70 20 53 69 7a 65 20 7b 46 31 37  n Heap Size {F17
37020 33 35 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  350}.**.** The s
37030 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
37040 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61  _limit() interfa
37050 63 65 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66  ce places a "sof
37060 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74  t" limit.** on t
37070 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61  he amount of hea
37080 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61  p memory that ma
37090 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  y be allocated b
370a0 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 49 66 20  y SQLite..** If 
370b0 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f  an internal allo
370c0 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  cation is reques
370d0 74 65 64 20 74 68 61 74 20 77 6f 75 6c 64 20 65  ted that would e
370e0 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66  xceed the.** sof
370f0 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73  t heap limit, [s
37100 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
37110 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f  emory()] is invo
37120 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f  ked one or.** mo
37130 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65  re times to free
37140 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62   up some space b
37150 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61  efore the alloca
37160 74 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  tion is performe
37170 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d  d..**.** The lim
37180 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f  it is called "so
37190 66 74 22 2c 20 62 65 63 61 75 73 65 20 69 66 20  ft", because if 
371a0 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
371b0 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61  _memory()].** ca
371c0 6e 6e 6f 74 20 66 72 65 65 20 73 75 66 66 69 63  nnot free suffic
371d0 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70  ient memory to p
371e0 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74  revent the limit
371f0 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65   from being exce
37200 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d  eded,.** the mem
37210 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64  ory is allocated
37220 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20   anyway and the 
37230 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f  current operatio
37240 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a  n proceeds..**.*
37250 2a 20 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20  * A negative or 
37260 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e  zero value for N
37270 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72   means that ther
37280 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61  e is no soft hea
37290 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b  p limit and.** [
372a0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
372b0 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f  memory()] will o
372c0 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
372d0 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68  en memory is exh
372e0 61 75 73 74 65 64 2e 0a 2a 2a 20 54 68 65 20 64  austed..** The d
372f0 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72  efault value for
37300 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
37310 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  imit is zero..**
37320 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
37330 20 61 20 62 65 73 74 20 65 66 66 6f 72 74 20 74   a best effort t
37340 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74  o honor the soft
37350 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20   heap limit..** 
37360 42 75 74 20 69 66 20 74 68 65 20 73 6f 66 74 20  But if the soft 
37370 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f  heap limit canno
37380 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20 65 78  t be honored, ex
37390 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20  ecution will.** 
373a0 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 74  continue without
373b0 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69   error or notifi
373c0 63 61 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 73  cation.  This is
373d0 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74 20 69   why the limit i
373e0 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22 73  s.** called a "s
373f0 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49 74 20  oft" limit.  It 
37400 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79  is advisory only
37410 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f  ..**.** Prior to
37420 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
37430 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f 75 74  3.5.0, this rout
37440 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61  ine only constra
37450 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a  ined the memory.
37460 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ** allocated by 
37470 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20  a single thread 
37480 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  - the same threa
37490 64 20 69 6e 20 77 68 69 63 68 20 74 68 69 73 20  d in which this 
374a0 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e  routine.** runs.
374b0 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68    Beginning with
374c0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
374d0 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66 74 20  3.5.0, the soft 
374e0 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a  heap limit is.**
374f0 20 61 70 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20   applied to all 
37500 74 68 72 65 61 64 73 2e 20 54 68 65 20 76 61 6c  threads. The val
37510 75 65 20 73 70 65 63 69 66 69 65 64 20 66 6f 72  ue specified for
37520 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
37530 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70  imit.** is an up
37540 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65  per bound on the
37550 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c   total memory al
37560 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c  location for all
37570 20 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a 2a 20   threads. In.** 
37580 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74 68  version 3.5.0 th
37590 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68 61 6e  ere is no mechan
375a0 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e 67  ism for limiting
375b0 20 74 68 65 20 68 65 61 70 20 75 73 61 67 65 20   the heap usage 
375c0 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61  for.** individua
375d0 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a  l threads..**.**
375e0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
375f0 2a 2a 20 7b 46 31 36 33 35 31 7d 20 54 68 65 20  ** {F16351} The 
37600 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
37610 61 70 5f 6c 69 6d 69 74 28 4e 29 5d 20 69 6e 74  ap_limit(N)] int
37620 65 72 66 61 63 65 20 70 6c 61 63 65 73 20 61 20  erface places a 
37630 73 6f 66 74 20 6c 69 6d 69 74 0a 2a 2a 20 20 20  soft limit.**   
37640 20 20 20 20 20 20 20 6f 66 20 4e 20 62 79 74 65         of N byte
37650 73 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  s on the amount 
37660 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74  of heap memory t
37670 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63  hat may be alloc
37680 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ated.**         
37690 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
376a0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
376b0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
376c0 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 0a 2a 2a   at any point.**
376d0 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 69 6d            in tim
376e0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 32  e..**.** {F16352
376f0 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b  } If a call to [
37700 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
37710 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
37720 61 6c 6c 6f 63 28 29 5d 20 77 6f 75 6c 64 0a 2a  alloc()] would.*
37730 2a 20 20 20 20 20 20 20 20 20 20 63 61 75 73 65  *          cause
37740 20 74 68 65 20 74 6f 74 61 6c 20 61 6d 6f 75 6e   the total amoun
37750 74 20 6f 66 20 61 6c 6c 6f 63 61 74 65 64 20 6d  t of allocated m
37760 65 6d 6f 72 79 20 74 6f 20 65 78 63 65 65 64 20  emory to exceed 
37770 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
37780 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c  soft heap limit,
37790 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
377a0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
377b0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20   is invoked.**  
377c0 20 20 20 20 20 20 20 20 69 6e 20 61 6e 20 61 74          in an at
377d0 74 65 6d 70 74 20 74 6f 20 72 65 64 75 63 65 20  tempt to reduce 
377e0 74 68 65 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  the memory usage
377f0 20 70 72 69 6f 72 20 74 6f 20 70 72 6f 63 65 65   prior to procee
37800 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ding.**         
37810 20 77 69 74 68 20 74 68 65 20 6d 65 6d 6f 72 79   with the memory
37820 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 74 74 65   allocation atte
37830 6d 70 74 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33  mpt..**.** {F163
37840 35 33 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71  53} Calls to [sq
37850 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
37860 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
37870 6c 6f 63 28 29 5d 20 74 68 61 74 20 74 72 69 67  loc()] that trig
37880 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ger.**          
37890 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 64 75  attempts to redu
378a0 63 65 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 20  ce memory usage 
378b0 74 68 72 6f 75 67 68 20 74 68 65 20 73 6f 66 74  through the soft
378c0 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 20   heap limit.**  
378d0 20 20 20 20 20 20 20 20 6d 65 63 68 61 6e 69 73          mechanis
378e0 6d 20 63 6f 6e 74 69 6e 75 65 20 65 76 65 6e 20  m continue even 
378f0 69 66 20 74 68 65 20 61 74 74 65 6d 70 74 20 74  if the attempt t
37900 6f 20 72 65 64 75 63 65 20 6d 65 6d 6f 72 79 0a  o reduce memory.
37910 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 61 67  **          usag
37920 65 20 69 73 20 75 6e 73 75 63 63 65 73 73 66 75  e is unsuccessfu
37930 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 34  l..**.** {F16354
37940 7d 20 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20  } A negative or 
37950 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e  zero value for N
37960 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a   in a call to.**
37970 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
37980 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
37990 69 74 28 4e 29 5d 20 6d 65 61 6e 73 20 74 68 61  it(N)] means tha
379a0 74 20 74 68 65 72 65 20 69 73 20 6e 6f 20 73 6f  t there is no so
379b0 66 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68  ft.**          h
379c0 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 20 5b 73  eap limit and [s
379d0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
379e0 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e  emory()] will on
379f0 6c 79 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20  ly be.**        
37a00 20 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65    called when me
37a10 6d 6f 72 79 20 69 73 20 63 6f 6d 70 6c 65 74 65  mory is complete
37a20 6c 79 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a  ly exhausted..**
37a30 0a 2a 2a 20 7b 46 31 36 33 35 35 7d 20 54 68 65  .** {F16355} The
37a40 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66   default value f
37a50 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
37a60 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a   limit is zero..
37a70 2a 2a 0a 2a 2a 20 7b 46 31 36 33 35 38 7d 20 45  **.** {F16358} E
37a80 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ach call to [sql
37a90 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
37aa0 69 6d 69 74 28 4e 29 5d 20 6f 76 65 72 72 69 64  imit(N)] overrid
37ab0 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
37ac0 20 20 20 76 61 6c 75 65 73 20 73 65 74 20 62 79     values set by
37ad0 20 61 6c 6c 20 70 72 69 6f 72 20 63 61 6c 6c 73   all prior calls
37ae0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
37af0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
37b00 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t(int);../*.** C
37b10 41 50 49 33 52 45 46 3a 20 45 78 74 72 61 63 74  API3REF: Extract
37b20 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20   Metadata About 
37b30 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61  A Column Of A Ta
37b40 62 6c 65 20 7b 46 31 32 38 35 30 7d 0a 2a 2a 0a  ble {F12850}.**.
37b50 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
37b60 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61 74 61  returns metadata
37b70 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66 69   about a specifi
37b80 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70  c column of a sp
37b90 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 62 61  ecific.** databa
37ba0 73 65 20 74 61 62 6c 65 20 61 63 63 65 73 73 69  se table accessi
37bb0 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 5b 64  ble using the [d
37bc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37bd0 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61  on] handle.** pa
37be0 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
37bf0 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  t function argum
37c00 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ent..**.** The c
37c10 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66  olumn is identif
37c20 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ied by the secon
37c30 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  d, third and fou
37c40 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
37c50 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69  o.** this functi
37c60 6f 6e 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70  on. The second p
37c70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 68  arameter is eith
37c80 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  er the name of t
37c90 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28  he database.** (
37ca0 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65  i.e. "main", "te
37cb0 6d 70 22 20 6f 72 20 61 6e 20 61 74 74 61 63 68  mp" or an attach
37cc0 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e  ed database) con
37cd0 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63  taining the spec
37ce0 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f  ified.** table o
37cf0 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74 20 69 73  r NULL. If it is
37d00 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20   NULL, then all 
37d10 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
37d20 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64 0a  es are searched.
37d30 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65  ** for the table
37d40 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
37d50 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64 20 62  algorithm used b
37d60 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  y the database e
37d70 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 6f  ngine to.** reso
37d80 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64 20  lve unqualified 
37d90 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73  table references
37da0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72  ..**.** The thir
37db0 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72  d and fourth par
37dc0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20  ameters to this 
37dd0 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65  function are the
37de0 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d   table and colum
37df0 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65  n.** name of the
37e00 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c   desired column,
37e10 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e   respectively. N
37e20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
37e30 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61  parameters.** ma
37e40 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  y be NULL..**.**
37e50 20 4d 65 74 61 64 61 74 61 20 69 73 20 72 65 74   Metadata is ret
37e60 75 72 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67  urned by writing
37e70 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c   to the memory l
37e80 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20  ocations passed 
37e90 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e  as the 5th.** an
37ea0 64 20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72  d subsequent par
37eb0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73 20  ameters to this 
37ec0 66 75 6e 63 74 69 6f 6e 2e 20 41 6e 79 20 6f 66  function. Any of
37ed0 20 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73   these arguments
37ee0 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c   may be.** NULL,
37ef0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74   in which case t
37f00 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
37f10 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61   element of meta
37f20 64 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e  data is omitted.
37f30 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
37f40 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
37f50 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
37f60 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20  ><th> Parameter 
37f70 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54  <th> Output<br>T
37f80 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69  ype <th>  Descri
37f90 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  ption.**.** <tr>
37fa0 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f  <td> 5th <td> co
37fb0 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44  nst char* <td> D
37fc0 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e  ata type.** <tr>
37fd0 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f  <td> 6th <td> co
37fe0 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e  nst char* <td> N
37ff0 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63  ame of default c
38000 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
38010 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74  e.** <tr><td> 7t
38020 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
38030 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
38040 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54  column has a NOT
38050 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74   NULL constraint
38060 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68  .** <tr><td> 8th
38070 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20   <td> int       
38080 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63    <td> True if c
38090 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66  olumn is part of
380a0 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59   the PRIMARY KEY
380b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68  .** <tr><td> 9th
380c0 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20   <td> int       
380d0 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63    <td> True if c
380e0 6f 6c 75 6d 6e 20 69 73 20 41 55 54 4f 49 4e 43  olumn is AUTOINC
380f0 52 45 4d 45 4e 54 0a 2a 2a 20 3c 2f 74 61 62 6c  REMENT.** </tabl
38100 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
38110 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65  te>.**.** The me
38120 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  mory pointed to 
38130 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72  by the character
38140 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
38150 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65  ed for the.** de
38160 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61  claration type a
38170 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  nd collation seq
38180 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f  uence is valid o
38190 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65  nly until the ne
381a0 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e  xt.** call to an
381b0 79 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e  y SQLite API fun
381c0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ction..**.** If 
381d0 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74 61  the specified ta
381e0 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20  ble is actually 
381f0 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f  a view, an [erro
38200 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
38210 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ned..**.** If th
38220 65 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75  e specified colu
38230 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20 22  mn is "rowid", "
38240 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f  oid" or "_rowid_
38250 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 49 4e 54 45  " and an.** INTE
38260 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20  GER PRIMARY KEY 
38270 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20  column has been 
38280 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
38290 72 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75  red, then the ou
382a0 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  tput.** paramete
382b0 72 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74  rs are set for t
382c0 68 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  he explicitly de
382d0 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 49  clared column. I
382e0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a  f there is no.**
382f0 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
38300 61 72 65 64 20 49 4e 54 45 47 45 52 20 50 52 49  ared INTEGER PRI
38310 4d 41 52 59 20 4b 45 59 20 63 6f 6c 75 6d 6e 2c  MARY KEY column,
38320 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74   then the output
38330 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61  .** parameters a
38340 72 65 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77  re set as follow
38350 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a  s:.**.** <pre>.*
38360 2a 20 20 20 20 20 64 61 74 61 20 74 79 70 65 3a  *     data type:
38370 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20   "INTEGER".**   
38380 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75    collation sequ
38390 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a  ence: "BINARY".*
383a0 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20  *     not null: 
383b0 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79  0.**     primary
383c0 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61   key: 1.**     a
383d0 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30  uto increment: 0
383e0 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a  .** </pre>.**.**
383f0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d   This function m
38400 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d  ay load one or m
38410 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d  ore schemas from
38420 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e   database files.
38430 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20   If an.** error 
38440 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
38450 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  is process, or i
38460 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  f the requested 
38470 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a  table or column.
38480 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75  ** cannot be fou
38490 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  nd, an [error co
384a0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  de] is returned 
384b0 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  and an error mes
384c0 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20  sage left.** in 
384d0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
384e0 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65  nnection] (to be
384f0 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67   retrieved using
38500 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
38510 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41  ))..**.** This A
38520 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  PI is only avail
38530 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
38540 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
38550 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
38560 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
38570 4e 5f 4d 45 54 41 44 41 54 41 20 43 20 70 72 65  N_METADATA C pre
38580 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
38590 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74   defined..*/.int
385a0 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63   sqlite3_table_c
385b0 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a  olumn_metadata(.
385c0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
385d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
385e0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64   Connection hand
385f0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
38600 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20  ar *zDbName,    
38610 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
38620 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a  name or NULL */.
38630 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54    const char *zT
38640 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a  ableName,     /*
38650 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20   Table name */. 
38660 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f   const char *zCo
38670 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20  lumnName,    /* 
38680 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20  Column name */. 
38690 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a   char const **pz
386a0 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20  DataType,    /* 
386b0 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64  OUTPUT: Declared
386c0 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20   data type */.  
386d0 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43  char const **pzC
386e0 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f  ollSeq,     /* O
386f0 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e  UTPUT: Collation
38700 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a   sequence name *
38710 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c  /.  int *pNotNul
38720 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  l,              
38730 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
38740 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73  if NOT NULL cons
38750 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f  traint exists */
38760 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79  .  int *pPrimary
38770 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Key,           /
38780 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
38790 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66  f column part of
387a0 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41   PK */.  int *pA
387b0 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20  utoinc          
387c0 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
387d0 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69  True if column i
387e0 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74  s auto-increment
387f0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
38800 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20  PI3REF: Load An 
38810 45 78 74 65 6e 73 69 6f 6e 20 7b 46 31 32 36 30  Extension {F1260
38820 30 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  0}.**.** This in
38830 74 65 72 66 61 63 65 20 6c 6f 61 64 73 20 61 6e  terface loads an
38840 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f   SQLite extensio
38850 6e 20 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 74  n library from t
38860 68 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a  he named file..*
38870 2a 0a 2a 2a 20 7b 46 31 32 36 30 31 7d 20 54 68  *.** {F12601} Th
38880 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65  e sqlite3_load_e
38890 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72  xtension() inter
388a0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
388b0 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 20 20 20 20   load an.**     
388c0 20 20 20 20 20 53 51 4c 69 74 65 20 65 78 74 65       SQLite exte
388d0 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f  nsion library co
388e0 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66  ntained in the f
388f0 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a  ile zFile..**.**
38900 20 7b 46 31 32 36 30 32 7d 20 54 68 65 20 65 6e   {F12602} The en
38910 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72  try point is zPr
38920 6f 63 2e 0a 2a 2a 0a 2a 2a 20 7b 46 31 32 36 30  oc..**.** {F1260
38930 33 7d 20 7a 50 72 6f 63 20 6d 61 79 20 62 65 20  3} zProc may be 
38940 30 2c 20